Docs: Show typing info and parse INPUT/OUTPUT sections

build/sage_bootstrap/tarball.py

@@ -50,7 +50,7 @@ def __init__(self, tarball_name, package=None):
 
         INPUT:
 
-        - ``tarball_name`` - string. The full filename (``foo-1.3.tar.bz2``)
+        - ``tarball_name`` -- string. The full filename (``foo-1.3.tar.bz2``)
           of a tarball on the Sage mirror network.
         """
         self.__filename = tarball_name

environment-3.11-linux.yml

@@ -374,6 +374,7 @@ dependencies:
   - snowballstemmer=3.0.1=pyhd8ed1ab_0
   - soupsieve=2.8=pyhd8ed1ab_0
   - sphinx=8.2.3=pyhd8ed1ab_0
+  - sphinx-autodoc-typehints=3.2.0=pyhd8ed1ab_0
   - sphinx-basic-ng=1.0.0b2=pyhd8ed1ab_3
   - sphinx-copybutton=0.5.2=pyhd8ed1ab_1
   - sphinx-inline-tabs=2023.4.21=pyhd8ed1ab_1

pyproject.toml

@@ -228,6 +228,7 @@ docs = [
   "jupyter-sphinx",
   "python-dateutil",
   "sphinx",
+  "sphinx-autodoc-typehints",
   "sphinx-copybutton",
   "sphinx-inline-tabs",
 ]

src/doc/en/developer/coding_basics.rst

@@ -345,9 +345,25 @@ information. You can use the existing functions of Sage as templates.
 
    The INPUT block describes all arguments that the function accepts.
 
-   1. The type names should be descriptive, but do not have to represent the
-      exact Sage/Python types. For example, use "integer" for anything that
-      behaves like an integer, rather than "int" or "Integer".
+  1. Put type information first and foremost in the function signature
+     (Python / Cython annotations). Treat the signature as the single
+     authoritative place for ordinary type declarations. The INPUT
+     block must not restate obvious types already conveyed there.
+     Instead, use the INPUT block to document the *semantic constraints*
+     and any *non‑obvious* accepted forms:
+
+     - State mathematical or structural conditions: e.g. "prime integer",
+       "nonnegative", "an iterable of vertices", "a square matrix", etc.
+     - Mention coercion behavior, mutability expectations, or protocol
+       requirements ("must implement ``.degree()``", "anything with a
+       ``.parent()``").
+     - Only include explicit type names if they add information not present
+       in the annotation (e.g. symbolic vs numeric, sparse vs dense).
+
+     Avoid redundant phrases like "``n`` -- integer" when the signature reads
+     ``def f(n: int, ...)``; write instead "``n`` -- nonnegative" or
+     "``n`` -- number of iterations (>= 1)". Legacy docstrings may still show
+     the old style; new and updated code should follow this convention.
 
    2. Mention the default values of the input arguments when applicable.
 
@@ -394,6 +410,13 @@ information. You can use the existing functions of Sage as templates.
        to be sorted in the same way as the corresponding factors of the
        characteristic polynomial.
 
+    As for INPUT, do not repeat trivial typing information in the OUTPUT
+    block. Treat the function's return annotation (or an obviously implied
+    type) as authoritative. Do NOT write just ``OUTPUT: integer`` or
+    ``OUTPUT: list`` when the signature already makes this clear (e.g.,
+    ``def rank(self) -> int``). Instead, explain the semantic meaning,
+    constraints, structure, and any subtleties.
+
 -  An **EXAMPLES** block for examples. This is not optional.
 
    These examples are used for documentation, but they are also

src/sage/algebras/fusion_rings/fusion_double.py

@@ -243,7 +243,7 @@ def s_ij(self, i, j, unitary=False, base_coercion=True):
 
         INPUT:
 
-        - ``i``, ``j``, -- a pair of basis elements
+        - ``i``, ``j`` -- a pair of basis elements
         - ``unitary`` -- boolean (default: ``False``); set to ``True`` to
           obtain the unitary `S`-matrix
 

src/sage/arith/misc.py

@@ -284,7 +284,7 @@ def bernoulli(n, algorithm='default', num_threads=1):
     INPUT:
 
     - ``n`` -- integer
-    - ``algorithm``:
+    - ``algorithm`` -- one of the following:
 
       - ``'default'`` -- use 'flint' for n <= 20000, then 'arb' for n <= 300000
         and 'bernmm' for larger values (this is just a heuristic, and not guaranteed
@@ -4056,8 +4056,8 @@ def multinomial(*ks):
 
     INPUT:
 
-    - either an arbitrary number of integer arguments `k_1,\dots,k_n`
-    - or an iterable (e.g. a list) of integers `[k_1,\dots,k_n]`
+    - ``*ks`` -- either an arbitrary number of integer arguments `k_1,\dots,k_n`
+      or an iterable (e.g. a list) of integers `[k_1,\dots,k_n]`
 
     OUTPUT: the integer:
 

src/sage/calculus/desolvers.py

@@ -1507,7 +1507,7 @@ def desolve_odeint(des, ics, times, dvars, ivar=None, compute_jac=False, args=()
     :func:`~scipy:scipy.integrate.odeint` function from
     :mod:`scipy:scipy.integrate`):
 
-    - ``rtol``, ``atol`` : float
+    - ``rtol``, ``atol`` -- float
       The input parameters ``rtol`` and ``atol`` determine the error
       control performed by the solver.  The solver will control the
       vector, `e`, of estimated local errors in `y`, according to an
@@ -1521,33 +1521,33 @@ def desolve_odeint(des, ics, times, dvars, ivar=None, compute_jac=False, args=()
 
       ``rtol`` and ``atol`` can be either vectors the same length as `y` or scalars.
 
-    - ``tcrit`` : array
+    - ``tcrit`` -- array
       Vector of critical points (e.g. singularities) where integration
       care should be taken.
 
-    - ``h0`` : float, (0: solver-determined)
+    - ``h0`` -- float, (0: solver-determined)
       The step size to be attempted on the first step.
 
-    - ``hmax`` : float, (0: solver-determined)
+    - ``hmax`` -- float, (0: solver-determined)
       The maximum absolute step size allowed.
 
-    - ``hmin`` : float, (0: solver-determined)
+    - ``hmin`` -- float, (0: solver-determined)
       The minimum absolute step size allowed.
 
-    - ``ixpr`` : boolean.
+    - ``ixpr`` -- boolean.
       Whether to generate extra printing at method switches.
 
-    - ``mxstep`` : integer, (0: solver-determined)
+    - ``mxstep``  -- integer, (0: solver-determined)
       Maximum number of (internally defined) steps allowed for each
       integration point in t.
 
-    - ``mxhnil`` : integer, (0: solver-determined)
+    - ``mxhnil`` -- integer, (0: solver-determined)
       Maximum number of messages printed.
 
-    - ``mxordn`` : integer, (0: solver-determined)
+    - ``mxordn`` -- integer, (0: solver-determined)
       Maximum order to be allowed for the nonstiff (Adams) method.
 
-    - ``mxords`` : integer, (0: solver-determined)
+    - ``mxords`` -- integer, (0: solver-determined)
       Maximum order to be allowed for the stiff (BDF) method.
 
     OUTPUT: a list with the solution of the system at each time in ``times``

src/sage/categories/affine_weyl_groups.py

@@ -217,7 +217,7 @@ def affine_grassmannian_to_partition(self):
 
             INPUT:
 
-            - ``self`` is affine Grassmannian element of the affine Weyl group of type `A_k^{(1)}` (i.e. all reduced words end in 0)
+            - ``self`` -- an affine Grassmannian element of the affine Weyl group of type `A_k^{(1)}` (i.e. all reduced words end in 0)
 
             OUTPUT: `k`-bounded partition
 

src/sage/categories/fields.py

@@ -635,7 +635,7 @@ def ideal(self, *gens, **kwds):
 
             INPUT:
 
-            - an element or a list/tuple/sequence of elements, the generators
+            - ``gens`` -- an element or a list/tuple/sequence of elements, the generators
 
             Any named arguments are ignored.
 

src/sage/categories/magmas.py

@@ -864,6 +864,7 @@ def multiplication_table(self, names='letters', elements=None):
                 of the elements themselves.
               * a list - a list of strings, where the length
                 of the list equals the number of elements.
+
             - ``elements`` -- (default: ``None``) a list of
               elements of the magma, in forms that can be
               coerced into the structure, eg. their string

src/sage/categories/rings.py

@@ -978,7 +978,7 @@ def ideal(self, *args, **kwds):
 
             INPUT:
 
-            - an element or a list/tuple/sequence of elements, the generators
+            - ``args`` -- an element or a list/tuple/sequence of elements, the generators
 
             - ``coerce`` -- boolean (default: ``True``); whether to first coerce
               the elements into this ring. This must be a keyword

src/sage/coding/guruswami_sudan/utils.py

@@ -116,7 +116,7 @@ def solve_degree2_to_integer_range(a, b, c):
 
     INPUT:
 
-    - ``a``, ``b`` and ``c`` -- coefficients of a second degree equation, ``a``
+    - ``a``, ``b``, ``c`` -- coefficients of a second degree equation, ``a``
       being the coefficient of the higher degree term
 
     EXAMPLES::

src/sage/coding/linear_code_no_metric.py

@@ -671,7 +671,7 @@ def is_information_set(self, positions):
 
         INPUT:
 
-        - A list of positions, i.e. integers in the range 0 to `n-1` where `n`
+        - ``positions`` -- list of positions, i.e. integers in the range 0 to `n-1` where `n`
           is the length of ``self``.
 
         OUTPUT: boolean indicating whether the positions form an information set

src/sage/coding/source_coding/huffman.py

@@ -451,10 +451,6 @@ def encoding_table(self):
         r"""
         Return the current encoding table.
 
-        INPUT:
-
-        - None.
-
         OUTPUT: a dictionary associating an alphabetic symbol to a Huffman encoding
 
         EXAMPLES::
@@ -492,10 +488,6 @@ def tree(self):
         r"""
         Return the Huffman tree corresponding to the current encoding.
 
-        INPUT:
-
-        - None.
-
         OUTPUT: the binary tree representing a Huffman code
 
         EXAMPLES::

src/sage/combinat/bijectionist.py

@@ -1107,7 +1107,7 @@
 
         INPUT:
 
-        - one or more pairs of `(\tilde A, \tilde Z)`, where `\tilde
+        - ``elements_distributions`` -- one or more pairs of `(\tilde A, \tilde Z)`, where `\tilde
           A\subseteq A` and `\tilde Z` is a list of values in `Z` of
           the same size as `\tilde A`
 
@@ -3131,7 +3131,7 @@
     sage: bij = Bijectionist(sum(As, []), sum(Bs, []))
     sage: bij.set_statistics((lambda x: x[0], lambda x: x[0]))
     sage: bij.set_intertwining_relations((2, c1, c1), (1, c2, c2))
     sage: l = list(bij.solutions_iterator()); len(l)                            # long time -- (2.7 seconds with SCIP on AMD Ryzen 5 PRO 3500U w/ Radeon Vega Mobile Gfx)
     64
 
 A brute force check would be difficult::
@@ -3159,7 +3159,7 @@
     sage: A = sum(As, [])
     sage: respects_c1 = lambda s: all(c1(a1, a2) not in A or s[c1(a1, a2)] == c1(s[a1], s[a2]) for a1 in A for a2 in A)
     sage: respects_c2 = lambda s: all(c2(a1) not in A or s[c2(a1)] == c2(s[a1]) for a1 in A)
     sage: l2 = [s for s in it if respects_c1(s) and respects_c2(s)]             # long time -- (17 seconds on AMD Ryzen 5 PRO 3500U w/ Radeon Vega Mobile Gfx)
     sage: sorted(l1, key=lambda s: tuple(s.items())) == l2                      # long time
     True
 

src/sage/combinat/combinat.py

@@ -812,7 +812,7 @@ def stirling_number1(n, k, algorithm='gap') -> Integer:
 
     - ``n`` -- nonnegative machine-size integer
     - ``k`` -- nonnegative machine-size integer
-    - ``algorithm``:
+    - ``algorithm`` -- one of the following:
 
       * ``'gap'`` -- default; use GAP's ``Stirling1`` function
       * ``'flint'`` -- use flint's ``arith_stirling_number_1u`` function
@@ -870,7 +870,7 @@ def stirling_number2(n, k, algorithm=None) -> Integer:
 
     - ``n`` -- nonnegative machine-size integer
     - ``k`` -- nonnegative machine-size integer
-    - ``algorithm``:
+    - ``algorithm`` -- one of the following:
 
       * ``None`` -- default; use native implementation
       * ``'flint'`` -- use flint's ``arith_stirling_number_2`` function

src/sage/combinat/finite_state_machine.py

@@ -2566,10 +2566,10 @@ class FiniteStateMachine(SageObject):
 
       #. an other instance of a finite state machine.
 
-    - ``initial_states`` and ``final_states`` -- the initial and
+    - ``initial_states``, ``final_states`` -- the initial and
       final states of this machine
 
-    - ``input_alphabet`` and ``output_alphabet`` -- the input and
+    - ``input_alphabet``, ``output_alphabet`` -- the input and
       output alphabets of this machine
 
     - ``determine_alphabets`` -- if ``True``, then the function
@@ -5678,7 +5678,7 @@ def process(self, *args, **kwargs):
           list or tuple of tracks, each of which can be a list or an
           iterable with entries from the input alphabet.
 
-        - ``initial_state`` or ``initial_states`` -- the initial
+        - ``initial_state``, ``initial_states`` -- the initial
           state(s) in which the machine starts. Either specify a
           single one with ``initial_state`` or a list of them with
           ``initial_states``. If both are given, ``initial_state``
@@ -9395,9 +9395,10 @@ def graph(self, edge_labels='words_in_out'):
         INPUT:
 
         - ``edge_label`` -- (default: ``'words_in_out'``) can be
-            - ``'words_in_out'`` (labels will be strings ``'i|o'``)
-            - a function with which takes as input a transition
-              and outputs (returns) the label
+
+          - ``'words_in_out'`` (labels will be strings ``'i|o'``)
+          - a function with which takes as input a transition
+            and outputs (returns) the label
 
         OUTPUT: a :class:`directed graph <DiGraph>`
 
@@ -11286,7 +11287,7 @@ def process(self, *args, **kwargs):
           list or tuple of tracks, each of which can be a list or an
           iterable with entries from the input alphabet.
 
-        - ``initial_state`` or ``initial_states`` -- the initial
+        - ``initial_state``, ``initial_states`` -- the initial
           state(s) in which the machine starts. Either specify a
           single one with ``initial_state`` or a list of them with
           ``initial_states``. If both are given, ``initial_state``
@@ -12369,7 +12370,7 @@ def process(self, *args, **kwargs):
           list or tuple of tracks, each of which can be a list or an
           iterable with entries from the input alphabet.
 
-        - ``initial_state`` or ``initial_states`` -- the initial
+        - ``initial_state``, ``initial_states`` -- the initial
           state(s) in which the machine starts. Either specify a
           single one with ``initial_state`` or a list of them with
           ``initial_states``. If both are given, ``initial_state``
@@ -13579,7 +13580,7 @@ class FSMProcessIterator(SageObject, Iterator):
       list or tuple of tracks, each of which can be a list or an
       iterable with entries from the input alphabet.
 
-    - ``initial_state`` or ``initial_states`` -- the initial
+    - ``initial_state``, ``initial_states`` -- the initial
       state(s) in which the machine starts. Either specify a
       single one with ``initial_state`` or a list of them with
       ``initial_states``. If both are given, ``initial_state``

src/sage/databases/cubic_hecke_db.py

@@ -929,6 +929,7 @@ def read_matrix_representation(self, representation_type, monomial_tietze, ring_
         r"""
         Return the matrix representations of the given monomial (in Tietze form)
         if it has been stored in the file cache before.
+
         INPUT:
 
         - ``representation_type`` -- an element of

src/sage/databases/sql_db.py

@@ -75,9 +75,10 @@
 #                  https://www.gnu.org/licenses/
 # ****************************************************************************
 
-import sqlite3 as sqlite
 import os
 import re
+import sqlite3 as sqlite
+
 from sage.misc.temporary_file import tmp_filename
 from sage.structure.sage_object import SageObject
 
@@ -412,7 +413,7 @@ def __init__(self, database, *args, **kwds):
         - ``query_dict`` -- dictionary specifying the query itself. The
           format is::
 
-              {'table_name':'tblname', 'display_cols':['col1', 'col2','col3'], 'expression': [col, operator, value]}
+            {'table_name':'tblname', 'display_cols':['col1', 'col2','col3'], 'expression': [col, operator, value]}
 
         NOTE:
             Every SQL type we are using is ultimately represented as a string,
@@ -719,7 +720,7 @@ def intersect(self, other, join_table=None, join_dict=None,
           the new query. (Must include a mapping for all tables, including
           those previously joined in either query). Structure is given by::
 
-              {'join_table1':('corr_base_col1', 'col1'), 'join_table2':('corr_base_col2', 'col2')}
+            {'join_table1':('corr_base_col1', 'col1'), 'join_table2':('corr_base_col2', 'col2')}
 
           where ``join_table1`` is to be joined with ``join_table`` on
           ``join_table.corr_base_col1 = join_table1.col1``
@@ -847,11 +848,13 @@ def union(self, other, join_table=None, join_dict=None, in_place=False):
         INPUT:
 
         - ``other`` -- the ``SQLQuery`` to union with
+
         - ``join_table`` -- base table to join on (This table should have at
           least one column in each table to join on).
+
         - ``join_dict`` -- dictionary that represents the join structure for
           the new query. (Must include a mapping for all tables, including
-          those previously joined in either query). Structure is given by::
+          those previously joined in either query). Structure is given by:
 
               {'join_table1':('corr_base_col1', 'col1'), 'join_table2':('corr_base_col2', 'col2')}
 

src/sage/dynamics/arithmetic_dynamics/projective_ds.py

@@ -6845,10 +6845,10 @@ def Lattes_to_curve(self, return_conjugation=False, check_lattes=False):
 
         INPUT:
 
-        ``return_conjugation`` -- (default: ``False``) if ``True``, then
-        return the conjugation that moves self to a map that comes from a
-        Short Weierstrass Model Elliptic curve
-        ``check_lattes`` -- (default: ``False``) if ``True``, then  will ValueError if not Lattes
+        - ``return_conjugation`` -- (default: ``False``) if ``True``, then
+          return the conjugation that moves self to a map that comes from a
+          Short Weierstrass Model Elliptic curve
+        - ``check_lattes`` -- (default: ``False``) if ``True``, then  will ValueError if not Lattes
 
         OUTPUT: a Short Weierstrass Model Elliptic curve which is isogenous to
         the Elliptic curve of 'self',