From b734f15e5b1add5902a9319773c0312fffd8d230 Mon Sep 17 00:00:00 2001 From: James Mitchell Date: Fri, 14 Aug 2026 15:59:30 +0100 Subject: [PATCH 1/3] order: remove doc for deprecated functions --- docs/source/data-structures/order/index.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/source/data-structures/order/index.rst b/docs/source/data-structures/order/index.rst index 6f371ce9..35ff1e80 100644 --- a/docs/source/data-structures/order/index.rst +++ b/docs/source/data-structures/order/index.rst @@ -15,7 +15,16 @@ or strings with respect to certain reduction orderings. .. seealso:: - :any:`Order`. + - :any:`Order` + - :any:`Alphabet` + +.. important:: + + The following functions are deprecated in v1.5.0 and will be removed v2.0.0: + + * ``lexicographical_compare``, please use :any:`lex_cmp` instead. + * ``recursive_path_compare`` please use :any:`rev_rpo_cmp` instead. + * ``shortlex_compare`` please use :any:`lenlex_cmp` instead. Contents -------- @@ -25,11 +34,8 @@ Contents lenlex_cmp lex_cmp - lexicographical_compare - recursive_path_compare rev_rpo_cmp rpo_cmp - shortlex_compare Full API -------- @@ -38,12 +44,6 @@ Full API .. autofunction:: lex_cmp -.. autofunction:: lexicographical_compare - -.. autofunction:: recursive_path_compare - .. autofunction:: rev_rpo_cmp .. autofunction:: rpo_cmp - -.. autofunction:: shortlex_compare From 211c4e710713a03bf1025cbba7a535931b465726 Mon Sep 17 00:00:00 2001 From: Codex OpenAI Date: Fri, 14 Aug 2026 16:09:44 +0100 Subject: [PATCH 2/3] order: add doc for Alphabet aware orders, and cleanup --- src/order.cpp | 250 +++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 195 insertions(+), 55 deletions(-) diff --git a/src/order.cpp b/src/order.cpp index 8e05b195..5d52d87a 100644 --- a/src/order.cpp +++ b/src/order.cpp @@ -45,30 +45,6 @@ namespace libsemigroups { } } - template - void bind_compare(py::module& m, - char const* name, - Compare compare, - AlphabetCompare alphabet_compare, - char const* doc) { - m.def( - name, - [compare](Word const& x, Word const& y) { return compare(x, y); }, - py::arg("x"), - py::arg("y"), - doc); - m.def( - name, - [alphabet_compare]( - Alphabet const& alphabet, Word const& x, Word const& y) { - return alphabet_compare(alphabet, x, y); - }, - py::arg("alphabet"), - py::arg("x"), - py::arg("y"), - doc); - } - template void bind_deprecated_compare(py::module& m, char const* old_name, @@ -88,111 +64,267 @@ namespace libsemigroups { template void bind_order_comparisons(py::module& m) { - bind_compare( - m, + m.def( "lex_cmp", [](Word const& x, Word const& y) { return lex_cmp(x, y); }, + py::arg("x"), + py::arg("y"), + R"pbdoc( +:sig=(x: str | list[int], y: str | list[int]) -> bool: +:only-document-once: +Compare two words lexicographically. + +:param x: the first word. +:type x: str | list[int] +:param y: the second word. +:type y: str | list[int] +:returns: Whether *x* is less than *y*. +:rtype: bool + +.. doctest:: python + + >>> from libsemigroups_pybind11 import lex_cmp + >>> lex_cmp("ab", "ba") + True + >>> lex_cmp([0, 1], [1, 0]) + True +)pbdoc"); + + m.def( + "lex_cmp", [](Alphabet const& alphabet, Word const& x, Word const& y) { return lex_cmp(alphabet, x, y); }, + py::arg("alphabet"), + py::arg("x"), + py::arg("y"), R"pbdoc( -:sig=(x: str | list[int], y: str | list[int]) -> bool: +:sig=(alphabet: Alphabet, x: str | list[int], y: str | list[int]) -> bool: :only-document-once: -Compare two words lexicographically. +Compare two words lexicographically using an alphabet. -The three-argument overload ``lex_cmp(alphabet, x, y)`` compares letters by -their positions in *alphabet*. It raises :any:`LibsemigroupsError` if either -word contains a letter that does not belong to *alphabet*. +Letters are compared by their positions in *alphabet*. +:param alphabet: the alphabet that determines the ordering of letters. +:type alphabet: Alphabet :param x: the first word. :type x: str | list[int] :param y: the second word. :type y: str | list[int] :returns: Whether *x* is less than *y*. :rtype: bool +:raises LibsemigroupsError: if either word contains a letter that does not + belong to *alphabet*. + +.. doctest:: python + + >>> from libsemigroups_pybind11 import Alphabet, lex_cmp + >>> alphabet = Alphabet("ba") + >>> lex_cmp(alphabet, "b", "a") + True )pbdoc"); - bind_compare( - m, + m.def( "lenlex_cmp", [](Word const& x, Word const& y) { return lenlex_cmp(x, y); }, + py::arg("x"), + py::arg("y"), + R"pbdoc( +:sig=(x: str | list[int], y: str | list[int]) -> bool: +:only-document-once: +Compare two words using len-lex ordering. + +Words are first ordered by length and then lexicographically. + +:param x: the first word. +:type x: str | list[int] +:param y: the second word. +:type y: str | list[int] +:returns: Whether *x* is less than *y*. +:rtype: bool + +.. doctest:: python + + >>> from libsemigroups_pybind11 import lenlex_cmp + >>> lenlex_cmp("bb", "aaa") + True + >>> lenlex_cmp([1, 1], [0, 0, 0]) + True +)pbdoc"); + + m.def( + "lenlex_cmp", [](Alphabet const& alphabet, Word const& x, Word const& y) { return lenlex_cmp(alphabet, x, y); }, + py::arg("alphabet"), + py::arg("x"), + py::arg("y"), R"pbdoc( -:sig=(x: str | list[int], y: str | list[int]) -> bool: +:sig=(alphabet: Alphabet, x: str | list[int], y: str | list[int]) -> bool: :only-document-once: -Compare two words using len-lex ordering. +Compare two words using len-lex ordering and an alphabet. -Words are first ordered by length and then lexicographically. The -three-argument overload ``lenlex_cmp(alphabet, x, y)`` compares letters by -their positions in *alphabet*. It raises :any:`LibsemigroupsError` if either -word contains a letter that does not belong to *alphabet*. +Words are first ordered by length and then lexicographically, with letters +compared by their positions in *alphabet*. +:param alphabet: the alphabet that determines the ordering of letters. +:type alphabet: Alphabet :param x: the first word. :type x: str | list[int] :param y: the second word. :type y: str | list[int] :returns: Whether *x* is less than *y*. :rtype: bool +:raises LibsemigroupsError: if either word contains a letter that does not + belong to *alphabet*. + +.. doctest:: python + + >>> from libsemigroups_pybind11 import Alphabet, lenlex_cmp + >>> alphabet = Alphabet("ba") + >>> lenlex_cmp(alphabet, "b", "a") + True )pbdoc"); - bind_compare( - m, + m.def( "rpo_cmp", [](Word const& x, Word const& y) { return rpo_cmp(x, y); }, + py::arg("x"), + py::arg("y"), + R"pbdoc( +:sig=(x: str | list[int], y: str | list[int]) -> bool: +:only-document-once: +Compare two words using recursive-path ordering. + +:param x: the first word. +:type x: str | list[int] +:param y: the second word. +:type y: str | list[int] +:returns: Whether *x* is less than *y*. +:rtype: bool + +.. warning:: + This function has significantly worse performance than :any:`lenlex_cmp` + and :any:`lex_cmp`. + +.. doctest:: python + + >>> from libsemigroups_pybind11 import rpo_cmp + >>> rpo_cmp("a", "b") + True + >>> rpo_cmp([0], [1]) + True +)pbdoc"); + + m.def( + "rpo_cmp", [](Alphabet const& alphabet, Word const& x, Word const& y) { return rpo_cmp(alphabet, x, y); }, + py::arg("alphabet"), + py::arg("x"), + py::arg("y"), R"pbdoc( -:sig=(x: str | list[int], y: str | list[int]) -> bool: +:sig=(alphabet: Alphabet, x: str | list[int], y: str | list[int]) -> bool: :only-document-once: -Compare two words using recursive-path ordering. +Compare two words using recursive-path ordering and an alphabet. -The three-argument overload ``rpo_cmp(alphabet, x, y)`` compares letters by -their positions in *alphabet*. It raises :any:`LibsemigroupsError` if either -word contains a letter that does not belong to *alphabet*. +Letters are compared by their positions in *alphabet*. +:param alphabet: the alphabet that determines the ordering of letters. +:type alphabet: Alphabet :param x: the first word. :type x: str | list[int] :param y: the second word. :type y: str | list[int] :returns: Whether *x* is less than *y*. :rtype: bool +:raises LibsemigroupsError: if either word contains a letter that does not + belong to *alphabet*. .. warning:: This function has significantly worse performance than :any:`lenlex_cmp` and :any:`lex_cmp`. + +.. doctest:: python + + >>> from libsemigroups_pybind11 import Alphabet, rpo_cmp + >>> alphabet = Alphabet("ba") + >>> rpo_cmp(alphabet, "b", "a") + True )pbdoc"); - bind_compare( - m, + m.def( "rev_rpo_cmp", [](Word const& x, Word const& y) { return rev_rpo_cmp(x, y); }, + py::arg("x"), + py::arg("y"), + R"pbdoc( +:sig=(x: str | list[int], y: str | list[int]) -> bool: +:only-document-once: +Compare two words using reversed recursive-path ordering. + +This is recursive-path ordering applied after reading both words from right to +left. + +:param x: the first word. +:type x: str | list[int] +:param y: the second word. +:type y: str | list[int] +:returns: Whether *x* is less than *y*. +:rtype: bool + +.. warning:: + This function has significantly worse performance than :any:`lenlex_cmp` + and :any:`lex_cmp`. + +.. doctest:: python + + >>> from libsemigroups_pybind11 import rev_rpo_cmp + >>> rev_rpo_cmp("a", "b") + True + >>> rev_rpo_cmp([0], [1]) + True +)pbdoc"); + + m.def( + "rev_rpo_cmp", [](Alphabet const& alphabet, Word const& x, Word const& y) { return rev_rpo_cmp(alphabet, x, y); }, + py::arg("alphabet"), + py::arg("x"), + py::arg("y"), R"pbdoc( -:sig=(x: str | list[int], y: str | list[int]) -> bool: +:sig=(alphabet: Alphabet, x: str | list[int], y: str | list[int]) -> bool: :only-document-once: -Compare two words using reversed recursive-path ordering. +Compare two words using reversed recursive-path ordering and an alphabet. This is recursive-path ordering applied after reading both words from right to -left. The three-argument overload ``rev_rpo_cmp(alphabet, x, y)`` compares -letters by their positions in *alphabet*. It raises -:any:`LibsemigroupsError` if either word contains a letter that does not belong -to *alphabet*. +left, with letters compared by their positions in *alphabet*. +:param alphabet: the alphabet that determines the ordering of letters. +:type alphabet: Alphabet :param x: the first word. :type x: str | list[int] :param y: the second word. :type y: str | list[int] :returns: Whether *x* is less than *y*. :rtype: bool +:raises LibsemigroupsError: if either word contains a letter that does not + belong to *alphabet*. .. warning:: This function has significantly worse performance than :any:`lenlex_cmp` and :any:`lex_cmp`. + +.. doctest:: python + + >>> from libsemigroups_pybind11 import Alphabet, rev_rpo_cmp + >>> alphabet = Alphabet("ba") + >>> rev_rpo_cmp(alphabet, "b", "a") + True )pbdoc"); bind_deprecated_compare( @@ -322,8 +454,16 @@ respectively, in new code. The recursive-path ordering, as described in :cite:`Jantzen2012aa` (Definition 1.2.14, page 24). - + This is deprecated; use :any:`Order.rpo` instead. + +.. doctest:: python + + >>> from libsemigroups_pybind11 import Order + >>> Order.lenlex + + >>> Order.shortlex == Order.lenlex + True )pbdoc") .value("none", Order::none) .value("lenlex", Order::lenlex) From 4d2fca7aea68e34ca3177665103e0c9fdb1923b5 Mon Sep 17 00:00:00 2001 From: James Mitchell Date: Fri, 14 Aug 2026 16:14:47 +0100 Subject: [PATCH 3/3] order: remove no longer used doc --- src/order.cpp | 60 +++++---------------------------------------------- 1 file changed, 5 insertions(+), 55 deletions(-) diff --git a/src/order.cpp b/src/order.cpp index 5d52d87a..1953dd65 100644 --- a/src/order.cpp +++ b/src/order.cpp @@ -49,8 +49,7 @@ namespace libsemigroups { void bind_deprecated_compare(py::module& m, char const* old_name, char const* new_name, - Compare compare, - char const* doc) { + Compare compare) { m.def( old_name, [old_name, new_name, compare](Word const& x, Word const& y) { @@ -58,8 +57,7 @@ namespace libsemigroups { return compare(x, y); }, py::arg("x"), - py::arg("y"), - doc); + py::arg("y")); } template @@ -331,67 +329,19 @@ left, with letters compared by their positions in *alphabet*. m, "lexicographical_compare", "lex_cmp", - [](Word const& x, Word const& y) { return lex_cmp(x, y); }, - R"pbdoc( -:sig=(x: str | list[int], y: str | list[int]) -> bool: -:only-document-once: -Compare two words lexicographically. - -:param x: the first word. -:type x: str | list[int] -:param y: the second word. -:type y: str | list[int] -:returns: Whether *x* is less than *y*. -:rtype: bool - -.. deprecated:: 1.5 - This will be removed from ``libsemigroups_pybind11`` in v2. Instead, use - :any:`lex_cmp`. -)pbdoc"); + [](Word const& x, Word const& y) { return lex_cmp(x, y); }); bind_deprecated_compare( m, "shortlex_compare", "lenlex_cmp", - [](Word const& x, Word const& y) { return lenlex_cmp(x, y); }, - R"pbdoc( -:sig=(x: str | list[int], y: str | list[int]) -> bool: -:only-document-once: -Compare two words using len-lex ordering. - -:param x: the first word. -:type x: str | list[int] -:param y: the second word. -:type y: str | list[int] -:returns: Whether *x* is less than *y*. -:rtype: bool - -.. deprecated:: 1.5 - This will be removed from ``libsemigroups_pybind11`` in v2. Instead, use - :any:`lenlex_cmp`. -)pbdoc"); + [](Word const& x, Word const& y) { return lenlex_cmp(x, y); }); bind_deprecated_compare( m, "recursive_path_compare", "rev_rpo_cmp", - [](Word const& x, Word const& y) { return rev_rpo_cmp(x, y); }, - R"pbdoc( -:sig=(x: str | list[int], y: str | list[int]) -> bool: -:only-document-once: -Compare two words using reversed recursive-path ordering. - -:param x: the first word. -:type x: str | list[int] -:param y: the second word. -:type y: str | list[int] -:returns: Whether *x* is less than *y*. -:rtype: bool - -.. deprecated:: 1.5 - This will be removed from ``libsemigroups_pybind11`` in v2. Instead, use - :any:`rev_rpo_cmp`. -)pbdoc"); + [](Word const& x, Word const& y) { return rev_rpo_cmp(x, y); }); } } // namespace