gh-40235: Annoate methods with `Self`
    
<!-- ^ Please provide a concise and informative title. -->
<!-- ^ Don't put issue numbers in the title, do this in the PR
description below. -->
<!-- ^ For example, instead of "Fixes #12345" use "Introduce new method
to calculate 1 + 2". -->
<!-- v Describe your changes below in detail. -->
<!-- v Why is this change required? What problem does it solve? -->
<!-- v If this PR resolves an open issue, please link to it here. For
example, "Fixes #12345". -->

Wanting to join the annoate-return-types-club, some methods that return
`self` are annoted by `typing.Self`.

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->

- [ ] The title is concise and informative.
- [ ] The description explains in detail what this PR is about.
- [ ] I have linked a relevant issue or discussion.
- [ ] I have created tests covering the changes.
- [ ] I have updated the documentation and checked the documentation
preview.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on. For example,
-->
<!-- - #12345: short description why this is a dependency -->
<!-- - #34567: ... -->
    
URL: #40235
Reported by: Tobias Diez
Reviewer(s): Vincent Macri

Author: Release Manager

src/sage/algebras/cellular_basis.py

@@ -108,9 +108,11 @@
 #                  https://www.gnu.org/licenses/
 # ****************************************************************************
 
-from sage.misc.cachefunc import cached_method
-from sage.combinat.free_module import CombinatorialFreeModule
+from typing import Self
+
 from sage.categories.algebras import Algebras
+from sage.combinat.free_module import CombinatorialFreeModule
+from sage.misc.cachefunc import cached_method
 
 
 class CellularBasis(CombinatorialFreeModule):
@@ -283,7 +285,7 @@ def cell_module_indices(self, la):
         """
         return self._algebra.cell_module_indices(la)
 
-    def cellular_basis(self):
+    def cellular_basis(self) -> Self:
         """
         Return the cellular basis of ``self``, which is ``self``.
 

src/sage/algebras/lie_algebras/bgg_dual_module.py

@@ -16,20 +16,22 @@
 #                  http://www.gnu.org/licenses/
 #*****************************************************************************
 
-from sage.misc.lazy_attribute import lazy_attribute
-from sage.misc.cachefunc import cached_method
+from typing import Self
+
+from sage.algebras.lie_algebras.verma_module import ModulePrinting
 from sage.categories.enumerated_sets import EnumeratedSets
 from sage.categories.monoids import Monoids
-from sage.structure.parent import Parent
-from sage.structure.indexed_generators import IndexedGenerators
-from sage.monoids.indexed_free_monoid import IndexedFreeAbelianMonoid, IndexedMonoid
 from sage.combinat.free_module import CombinatorialFreeModule
-from sage.sets.family import Family
-from sage.sets.finite_enumerated_set import FiniteEnumeratedSet
+from sage.data_structures.blas_dict import iaxpy
 from sage.matrix.constructor import matrix
+from sage.misc.cachefunc import cached_method
+from sage.misc.lazy_attribute import lazy_attribute
+from sage.monoids.indexed_free_monoid import IndexedFreeAbelianMonoid, IndexedMonoid
 from sage.rings.integer_ring import ZZ
-from sage.data_structures.blas_dict import iaxpy
-from sage.algebras.lie_algebras.verma_module import ModulePrinting
+from sage.sets.family import Family
+from sage.sets.finite_enumerated_set import FiniteEnumeratedSet
+from sage.structure.indexed_generators import IndexedGenerators
+from sage.structure.parent import Parent
 
 
 class BGGDualModule(CombinatorialFreeModule):
@@ -779,7 +781,9 @@ def cardinality(self):
             P = Phi.weight_lattice()
             coroots = Phi.root_lattice().simple_coroots()
             la = P._from_dict({i: weight.scalar(ac) for i, ac in coroots.items()})
-            from sage.combinat.crystals.monomial_crystals import CrystalOfNakajimaMonomials
+            from sage.combinat.crystals.monomial_crystals import (
+                CrystalOfNakajimaMonomials,
+            )
             return CrystalOfNakajimaMonomials(la).cardinality()
         from sage.rings.infinity import infinity
         return infinity
@@ -979,7 +983,7 @@ def _lift_on_basis(self, m):
             raise ValueError(f"{m} does not index a basis element")
         return self._indices._basis[m]
 
-    def dual(self):
+    def dual(self) -> Self:
         r"""
         Return the dual module of ``self``, which is ``self`` since simple
         modules are self-dual.

src/sage/categories/additive_magmas.py

@@ -9,16 +9,18 @@
 #                  https://www.gnu.org/licenses/
 # *****************************************************************************
 
-from sage.misc.lazy_import import LazyImport
-from sage.misc.abstract_method import abstract_method
-from sage.misc.cachefunc import cached_method
-from sage.categories.category_with_axiom import CategoryWithAxiom
-from sage.categories.category_singleton import Category_singleton
+from typing import Self
+
 from sage.categories.algebra_functor import AlgebrasCategory
 from sage.categories.cartesian_product import CartesianProductsCategory
+from sage.categories.category_singleton import Category_singleton
+from sage.categories.category_with_axiom import CategoryWithAxiom
 from sage.categories.homsets import HomsetsCategory
-from sage.categories.with_realizations import WithRealizationsCategory
 from sage.categories.sets_cat import Sets
+from sage.categories.with_realizations import WithRealizationsCategory
+from sage.misc.abstract_method import abstract_method
+from sage.misc.cachefunc import cached_method
+from sage.misc.lazy_import import LazyImport
 
 
 class AdditiveMagmas(Category_singleton):
@@ -384,8 +386,9 @@ def addition_table(self, names='letters', elements=None):
                 y| y z x
                 z| z x y
             """
-            from sage.matrix.operation_table import OperationTable
             import operator
+
+            from sage.matrix.operation_table import OperationTable
             return OperationTable(self, operation=operator.add,
                                   names=names, elements=elements)
 
@@ -596,7 +599,7 @@ def extra_super_categories(self):
 
     class AdditiveUnital(CategoryWithAxiom):
 
-        def additional_structure(self):
+        def additional_structure(self) -> Self:
             r"""
             Return whether ``self`` is a structure category.
 

src/sage/categories/cartesian_product.py

@@ -13,9 +13,14 @@
 #                  http://www.gnu.org/licenses/
 #*****************************************************************************
 
-from sage.misc.lazy_import import lazy_import
-from sage.categories.covariant_functorial_construction import CovariantFunctorialConstruction, CovariantConstructionCategory
+from typing import Self
+
+from sage.categories.covariant_functorial_construction import (
+    CovariantConstructionCategory,
+    CovariantFunctorialConstruction,
+)
 from sage.categories.pushout import MultivariateConstructionFunctor
+from sage.misc.lazy_import import lazy_import
 
 native_python_containers = {tuple, list, set, frozenset, range}
 
@@ -245,7 +250,7 @@ def _repr_object_names(self):
         # This method is only required for the capital `C`
         return "Cartesian products of %s" % (self.base_category()._repr_object_names())
 
-    def CartesianProducts(self):
+    def CartesianProducts(self) -> Self:
         """
         Return the category of (finite) Cartesian products of objects
         of ``self``.

src/sage/categories/category.py

@@ -103,19 +103,24 @@
 # ****************************************************************************
 
 import inspect
+from typing import Self
 from warnings import warn
+
+from sage.categories.category_cy_helper import (
+    _flatten_categories,
+    _sort_uniq,
+    category_sort_key,
+    join_as_tuple,
+)
 from sage.misc.abstract_method import abstract_method, abstract_methods_of_class
-from sage.misc.cachefunc import cached_method, cached_function
-from sage.misc.c3_controlled import _cmp_key, _cmp_key_named, C3_sorted_merge
+from sage.misc.c3_controlled import C3_sorted_merge, _cmp_key, _cmp_key_named
+from sage.misc.cachefunc import cached_function, cached_method
 from sage.misc.lazy_attribute import lazy_attribute
 from sage.misc.unknown import Unknown
 from sage.misc.weak_dict import WeakValueDictionary
-
+from sage.structure.dynamic_class import DynamicMetaclass, dynamic_class
 from sage.structure.sage_object import SageObject
 from sage.structure.unique_representation import UniqueRepresentation
-from sage.structure.dynamic_class import DynamicMetaclass, dynamic_class
-
-from sage.categories.category_cy_helper import category_sort_key, _sort_uniq, _flatten_categories, join_as_tuple
 
 _join_cache = WeakValueDictionary()
 
@@ -1045,7 +1050,7 @@ def _super_categories_for_classes(self):
     # Methods handling of full subcategories
     ##########################################################################
 
-    def additional_structure(self):
+    def additional_structure(self) -> Self:
         """
         Return whether ``self`` defines additional structure.
 
@@ -2214,7 +2219,7 @@ def _without_axiom(self, axiom):
         else:
             raise ValueError("Cannot remove axiom {} from {}".format(axiom, self))
 
-    def _without_axioms(self, named=False):
+    def _without_axioms(self, named=False) -> Self:
         r"""
         Return the category without the axioms that have been added
         to create it.

src/sage/categories/complete_discrete_valuation.py

@@ -10,6 +10,8 @@
 #**************************************************************************
 
 
+from typing import Self
+
 from sage.categories.category_singleton import Category_singleton
 from sage.categories.discrete_valuation import (
     DiscreteValuationFields,
@@ -97,7 +99,7 @@ def denominator(self):
             """
             return self.parent()(1)
 
-        def numerator(self):
+        def numerator(self) -> Self:
             """
             Return the numerator of this element, normalized in such a
             way that `x = x.numerator() / x.denominator()` always holds

src/sage/categories/covariant_functorial_construction.py

@@ -42,13 +42,15 @@
 #  Distributed under the terms of the GNU General Public License (GPL)
 #                  http://www.gnu.org/licenses/
 #******************************************************************************
+from typing import Self
+
+from sage.categories.category import Category
 from sage.misc.cachefunc import cached_function, cached_method
 from sage.misc.lazy_attribute import lazy_class_attribute
 from sage.misc.lazy_import import LazyImport
-from sage.categories.category import Category
+from sage.structure.dynamic_class import DynamicMetaclass
 from sage.structure.sage_object import SageObject
 from sage.structure.unique_representation import UniqueRepresentation
-from sage.structure.dynamic_class import DynamicMetaclass
 
 
 class CovariantFunctorialConstruction(UniqueRepresentation, SageObject):
@@ -624,7 +626,7 @@ def is_construction_defined_by_base(self):
         f = self._functor_category
         return not any(hasattr(C, f) for C in base.super_categories())
 
-    def additional_structure(self):
+    def additional_structure(self) -> Self | None:
         r"""
         Return the additional structure defined by ``self``.
 

src/sage/categories/dedekind_domains.py

@@ -6,6 +6,8 @@
 #  Distributed under the terms of the GNU General Public License (GPL)
 #                  https://www.gnu.org/licenses/
 # *****************************************************************************
+from typing import Self
+
 from sage.categories.category import Category
 from sage.categories.integral_domains import IntegralDomains
 
@@ -86,7 +88,7 @@ def is_integrally_closed(self) -> bool:
             """
             return True
 
-        def integral_closure(self):
+        def integral_closure(self) -> Self:
             r"""
             Return ``self`` since Dedekind domains are integrally closed.