Fix return self by reference

Author: james-d-mitchell

docs/source/main-algorithms/kambites/class.rst

@@ -20,11 +20,15 @@ Contents
     :signatures: short
 
     ~Kambites
+    Kambites.add_generating_pair
     Kambites.contains
+    Kambites.copy
     Kambites.currently_contains
     Kambites.generating_pairs
     Kambites.init
+    Kambites.kind
     Kambites.number_of_classes
+    Kambites.number_of_generating_pairs
     Kambites.presentation
     Kambites.reduce
     Kambites.reduce_no_run

libsemigroups_pybind11/congruence.py

@@ -35,6 +35,7 @@
 from .detail.decorators import (
     may_return_positive_infinity as _may_return_positive_infinity,
     copydoc as _copydoc,
+    returns_self as _returns_self,
 )
 
 from .detail import cong_intf
@@ -108,7 +109,7 @@ def get(self: Self, t: type):
         if t is _ToddCoxeter:
             return self._get_todd_coxeter()
         if t is _Kambites:
-            return self._get_kambites()
+            return _Kambites(self._get_kambites())
         return None
 
     def has(self: Self, t: type) -> bool:
@@ -136,6 +137,20 @@ def has(self: Self, t: type) -> bool:
             return self._has_kambites()
         return False
 
+    @_copydoc(_CongruenceWord.add_generating_pair)
+    @_returns_self
+    def add_generating_pair(self: Self, *args) -> Self:
+        return _to_cxx(self).add_generating_pair(*args)
+
+    @_copydoc(_CongruenceWord.copy)
+    def copy(self: Self) -> Self:
+        return Congruence(_to_cxx(self).copy())
+
+    @_copydoc(_CongruenceWord.init)
+    @_returns_self
+    def init(self: Self, *args) -> Self:
+        return _to_cxx(self).init(*args)
+
     @_copydoc(_CongruenceWord._number_of_classes)
     @_may_return_positive_infinity
     def number_of_classes(self: Self) -> int:

libsemigroups_pybind11/detail/decorators.py

@@ -79,6 +79,19 @@ def wrapper(self, *args, **kwargs):
     return wrapper
 
 
+def returns_self(func):
+    """
+    This function is a decorator for functions/methods that return self.
+    """
+
+    @wraps(func)
+    def wrapper(self, *args, **kwargs):
+        func(self, *args, **kwargs)
+        return self
+
+    return wrapper
+
+
 def template_params_as_kwargs(**kwargs_map):
     """
     Usage example:

libsemigroups_pybind11/kambites.py

@@ -22,6 +22,7 @@
 from _libsemigroups_pybind11 import (
     KambitesMultiStringView as _KambitesMultiStringView,
     KambitesWord as _KambitesWord,
+    KambitesString as _KambitesString,
     PresentationStrings as _PresentationStrings,
     PresentationWords as _PresentationWords,
     congruence_kind as _congruence_kind,
@@ -33,6 +34,7 @@
 from .detail.decorators import (
     may_return_positive_infinity as _may_return_positive_infinity,
     copydoc as _copydoc,
+    returns_self as _returns_self,
 )
 
 from .detail import cong_intf as _cong_intf
@@ -56,21 +58,48 @@ class Kambites(_CxxWrapper):
     def __init__(  # pylint: disable=super-init-not-called
         self: Self, *args, **kwargs
     ) -> None:
-        _cong_intf.raise_if_bad_args(*args, **kwargs)
-        if len(args) == 0:
-            Word = kwargs["Word"]
+        if (
+            len(args) == 1
+            and len(kwargs) == 0
+            and isinstance(
+                args[0],
+                (_KambitesWord, _KambitesMultiStringView, _KambitesString),
+            )
+        ):
+            self._cxx_obj = args[0]
         else:
-            assert len(args) == 2
-            if isinstance(args[1], _PresentationStrings):
-                Word = str
-            elif isinstance(args[1], _PresentationWords):
-                Word = List[int]
+            _cong_intf.raise_if_bad_args(*args, **kwargs)
+            if len(args) == 0:
+                Word = kwargs["Word"]
             else:
-                raise TypeError(
-                    f"expected the 2nd argument to be Presentation, but found {type(args[1])}"
-                )
+                assert len(args) == 2
+                if isinstance(args[1], _PresentationStrings):
+                    Word = str
+                elif isinstance(args[1], _PresentationWords):
+                    Word = List[int]
+                else:
+                    raise TypeError(
+                        f"expected the 2nd argument to be Presentation, but found {type(args[1])}"
+                    )
+            self._cxx_obj = self._py_to_cxx_type_dict[Word](*args)
+        if isinstance(self._cxx_obj, _KambitesWord):
+            self.Word = List[int]
+        else:
+            self.Word = str
+
+    @_copydoc(_KambitesWord.add_generating_pair)
+    @_returns_self
+    def add_generating_pair(self: Self, *args) -> Self:
+        return _to_cxx(self).add_generating_pair(*args)
+
+    @_copydoc(_KambitesWord.copy)
+    def copy(self: Self) -> Self:
+        return Kambites(_to_cxx(self).copy())
 
-        self._cxx_obj = self._py_to_cxx_type_dict[Word](*args)
+    @_copydoc(_KambitesWord.init)
+    @_returns_self
+    def init(self: Self, *args) -> Self:
+        return _to_cxx(self).init(*args)
 
     @_copydoc(_KambitesWord._number_of_classes)
     @_may_return_positive_infinity

src/cong.cpp

@@ -64,6 +64,7 @@ individual algorithms, such as :any:`Kambites`,
     >>> is_obviously_infinite(cong)
     True
     >>> cong.add_generating_pair([1, 1, 1], [])
+    <Congruence over <monoid presentation with 2 letters, 1 rule, and length 2> with 4 runners>
     >>> cong.number_of_classes()
     3
     >>> is_obviously_infinite(cong)

src/kambites.cpp

@@ -70,17 +70,10 @@ included for uniformity of interface between with
 :any:`KnuthBendixStringRewriteTrie`, :any:`ToddCoxeterWord`, and
 :any:`Congruence`.)pbdoc"sv;
 
-      auto extra_raises = R"pbdoc(
-:raises LibsemigroupsError:
-    if :any:`small_overlap_class` is not at least :math:`4`.
-)pbdoc"sv;
-
       def_construct_kind_presentation(
-          thing,
-          "Kambites",
-          doc{.detail = extra_detail, .raises = extra_raises});
+          thing, "Kambites", doc{.detail = extra_detail});
 
-      extra_raises = R"pbdoc(
+      auto extra_raises = R"pbdoc(
 :raises LibsemigroupsError: if *knd* is ``congruence_kind.onesided``.
 )pbdoc"sv;
 
@@ -105,7 +98,13 @@ raised.)pbdoc"sv;
           "Kambites",
           doc{.detail = extra_detail, .raises = extra_raises});
 
-      def_add_generating_pair(thing, "Kambites");
+      extra_raises = R"pbdoc(
+:raises TypeError:
+    if the type of the arguments is not the same as the type of the words in
+    :any:`Kambites.presentation`.
+)pbdoc"sv;
+
+      def_add_generating_pair(thing, "Kambites", doc{.raises = extra_raises});
 
       extra_raises = R"pbdoc(
 :raises LibsemigroupsError:
@@ -124,10 +123,11 @@ raised.)pbdoc"sv;
       extra_detail = R"pbdoc(If the :any:`Kambites.small_overlap_class`
 is not at least :math:`4`, then an exception is thrown.)pbdoc"sv;
 
-      def_reduce_no_run(thing, name, doc{.detail = extra_detail});
+      def_reduce_no_run(thing, "Kambites", doc{.detail = extra_detail});
 
-      def_reduce(
-          thing, name, doc{.detail = extra_detail, .raises = extra_raises});
+      def_reduce(thing,
+                 "Kambites",
+                 doc{.detail = extra_detail, .raises = extra_raises});
 
       ////////////////////////////////////////////////////////////////////////
       // Kambites specific stuff
@@ -169,6 +169,7 @@ at least :math:`n`.
       thing.def("ukkonen",
                 &Kambites_::ukkonen,
                 R"pbdoc(
+:sig=(self: Kambites) -> Ukkonen:
 Returns the generalised suffix tree used to compute pieces.
 
 This function returns the generalised suffix tree :any:`Ukkonen` object