Skip to content

Fix doc for keyword args + default constructors #284

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
james-d-mitchell merged 4 commits into from
Jun 19, 2025
Merged

Fix doc for keyword args + default constructors #284

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5c765f1
Lowercase kwargs everywhere
james-d-mitchell Jun 19, 2025
cb034ac
cong-common: correct the doc for default ctors
james-d-mitchell Jun 19, 2025
7becc73
sims: use keyword arg "word" instead of default ctor
james-d-mitchell Jun 19, 2025
1cf456c
Add TODO
james-d-mitchell Jun 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 33 additions & 23 deletions docs/pictures/to-table.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,29 +10,39 @@
\begin{document}

\begin{tabular}{l|c|c|c|c|c|c|c|c|c|c|c}
&
\rotatebox{90}{\texttt{Congruence}} &
\rotatebox{90}{\texttt{FroidurePin}} &
\rotatebox{90}{\texttt{InversePresentation}} &
\rotatebox{90}{\texttt{Kambites}} &
\rotatebox{90}{\texttt{KnuthBendix}} &
\rotatebox{90}{\texttt{Konieczny}} &
\rotatebox{90}{\texttt{Presentation}} &
\rotatebox{90}{\texttt{SchreierSims}} &
\rotatebox{90}{\texttt{Stephen}} &
\rotatebox{90}{\texttt{ToddCoxeter}}
\\
\midrule
\texttt{to(*args, Return=Congruence)} & \xmark & \cmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
\texttt{to(*args, Return=FroidurePin)} & \cmark & \xmark & \xmark & \cmark & \cmark & \xmark & \xmark & \xmark & \xmark & \cmark \\\hline
\texttt{to(*args, Return=InversePresentation)} & \xmark & \xmark & \cmark & \xmark & \xmark & \xmark & \cmark & \xmark & \xmark & \xmark \\\hline
\texttt{to(*args, Return=Kambites)} & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
\texttt{to(*args, Return=KnuthBendix)} & \xmark & \cmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \cmark \\\hline
\texttt{to(*args, Return=Konieczny)} & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
\texttt{to(*args, Return=Presentation)} & \xmark & \cmark & \xmark & \xmark & \cmark & \xmark & \cmark & \xmark & \xmark & \xmark \\\hline
\texttt{to(*args, Return=SchreierSims)} & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
\texttt{to(*args, Return=Stephen)} & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
\texttt{to(*args, Return=ToddCoxeter)} & \xmark & \cmark & \xmark & \xmark & \cmark & \xmark & \xmark & \xmark & \xmark & \xmark \\
&
\rotatebox{90}{\texttt{Congruence}} &
\rotatebox{90}{\texttt{FroidurePin}} &
\rotatebox{90}{\texttt{InversePresentation}} &
\rotatebox{90}{\texttt{Kambites}} &
\rotatebox{90}{\texttt{KnuthBendix}} &
\rotatebox{90}{\texttt{Konieczny}} &
\rotatebox{90}{\texttt{Presentation}} &
\rotatebox{90}{\texttt{SchreierSims}} &
\rotatebox{90}{\texttt{Stephen}} &
\rotatebox{90}{\texttt{ToddCoxeter}}
\\
\midrule
\texttt{to(*args, rtype=Congruence)} & \xmark & \cmark &
\xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
\texttt{to(*args, rtype=FroidurePin)} & \cmark & \xmark &
\xmark & \cmark & \cmark & \xmark & \xmark & \xmark & \xmark & \cmark \\\hline
\texttt{to(*args, rtype=InversePresentation)} & \xmark & \xmark &
\cmark & \xmark & \xmark & \xmark & \cmark & \xmark & \xmark & \xmark \\\hline
\texttt{to(*args, rtype=Kambites)} & \xmark & \xmark &
\xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
\texttt{to(*args, rtype=KnuthBendix)} & \xmark & \cmark &
\xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \cmark \\\hline
\texttt{to(*args, rtype=Konieczny)} & \xmark & \xmark &
\xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
\texttt{to(*args, rtype=Presentation)} & \xmark & \cmark &
\xmark & \xmark & \cmark & \xmark & \cmark & \xmark & \xmark & \xmark \\\hline
\texttt{to(*args, rtype=SchreierSims)} & \xmark & \xmark &
\xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
\texttt{to(*args, rtype=Stephen)} & \xmark & \xmark &
\xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark & \xmark \\\hline
\texttt{to(*args, rtype=ToddCoxeter)} & \xmark & \cmark &
\xmark & \xmark & \cmark & \xmark & \xmark & \xmark & \xmark & \xmark \\
\end{tabular}
% \cmark = implemented, \xmark = not yet implemented, -
% = not applicable
Expand Down
8 changes: 4 additions & 4 deletions docs/source/data-structures/presentations/to-inverse-present.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ This function throws a :any:`LibsemigroupsError` if
>>> presentation.add_rule(p, 'aaa', 'b')
>>> presentation.add_rule(p, 'bac', 'cab')

>>> ip = to(p, Return=(InversePresentation,))
>>> ip = to(p, rtype=(InversePresentation,))
>>> ip.alphabet()
'abcdef'
>>> ip.inverses()
Expand Down Expand Up @@ -139,10 +139,10 @@ not the same as that specified in *Return* and
>>> presentation.add_rule(ip, 'aaa', 'b')
>>> presentation.add_rule(ip, 'bac', 'cab')

>>> ip == to(ip, Return=(InversePresentation, str))
>>> ip == to(ip, rtype=(InversePresentation, str))
True

>>> iq = to(ip, Return=(InversePresentation, list[int]))
>>> iq = to(ip, rtype=(InversePresentation, list[int]))
>>> iq.alphabet()
[0, 1, 2]
>>> iq.inverses()
Expand Down Expand Up @@ -204,7 +204,7 @@ type of word specified in *Return*.
>>> iq = to(
... ip, # ip
... lambda x: chr(ord(x) + 11), # f
... Return=(InversePresentation, str)
... rtype=(InversePresentation, str)
... )
>>> iq.alphabet()
'lmn'
Expand Down
12 changes: 6 additions & 6 deletions docs/source/data-structures/presentations/to-present.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,16 +87,16 @@ not the same as that specified in *Return*, and
>>> p.rules
['ae', 'e', 'ea', 'e', 'be', 'e', 'eb', 'e', 'ce', 'e', 'ec', 'e', 'de', 'e', 'ed', 'e', 'ee', 'e', 'fe', 'e', 'ef', 'e']

>>> p == to(p, Return=(Presentation, str))
>>> p == to(p, rtype=(Presentation, str))
True

>>> q = to(p, Return=(Presentation, list[int]))
>>> q = to(p, rtype=(Presentation, list[int]))
>>> q.alphabet()
[0, 1, 2, 3, 4, 5]
>>> q.rules
[[0, 4], [4], [4, 0], [4], [1, 4], [4], [4, 1], [4], [2, 4], [4], [4, 2], [4], [3, 4], [4], [4, 3], [4], [4, 4], [4], [5, 4], [4], [4, 5], [4]]

>>> p == to(q, Return=(Presentation, str))
>>> p == to(q, rtype=(Presentation, str))
True

.. _presentation-and-function-to-presentation:
Expand Down Expand Up @@ -147,7 +147,7 @@ specified in *Return*.
>>> q = to(
... p, # p
... double, # f
... Return=(Presentation, list[int])
... rtype=(Presentation, list[int])
... )
>>> q.alphabet()
[0, 4, 8, 12]
Expand Down Expand Up @@ -205,7 +205,7 @@ enumerates *kb*) prior to calling this function.

>>> kb = KnuthBendix(congruence_kind.twosided, p1)
>>> kb.run()
>>> p2 = to(kb, Return=(Presentation,))
>>> p2 = to(kb, rtype=(Presentation,))
>>> for p in [p1, p2]:
... presentation.sort_each_rule(p)
... presentation.sort_rules(p)
Expand Down Expand Up @@ -261,6 +261,6 @@ to calling this function.
>>> b4 = Bipartition([[1, 2], [3, -3], [4, -4], [-1, -2]])
>>> S = FroidurePin(b1, b2, b3, b4)

>>> p = to(S, Return=(Presentation, str))
>>> p = to(S, rtype=(Presentation, str))
>>> len(p.alphabet()) == 4
True
6 changes: 3 additions & 3 deletions docs/source/data-structures/to-function.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,11 @@ This page contains links to the documentation of the uses of the function
to another type. These mostly only apply to the types implementing the main
algorithms in ``libsemigroups_pybind11``.

For example, to convert a :any:`ToddCoxeter` ``tc`` object to a
:any:`FroidurePin` object, you can simply do ``to(tc, Return=(FroidurePin,))``.
For example, to convert a :any:`ToddCoxeter` object ``tc`` to a
:any:`FroidurePin` object, you can simply do ``to(tc, rtype=(FroidurePin,))``.

A summary of the possible conversions available in ``libsemigroups_pybind11`` of
``to(FromType, Return=(ToType,))`` are given below, where the rows correspond to
``to(FromType, rtype=(ToType,))`` are given below, where the rows correspond to
``ToType`` and the columns to ``FromType``:

.. image:: ../../pictures/to-table.svg
Expand Down
2 changes: 1 addition & 1 deletion docs/source/main-algorithms/congruence/to-cong.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ This will throw a :any:`LibsemigroupsError` if *wg* is not the
... congruence_kind.twosided, # knd
... S, # fpb
... S.right_cayley_graph(), # wg
... Return=(Congruence, str),
... rtype=(Congruence, str),
... )

>>> cong.run()
Expand Down
10 changes: 5 additions & 5 deletions docs/source/main-algorithms/froidure-pin/to-froidure-pin.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ This function throws a :any:`LibsemigroupsError` if ``cong.kind`` is not
>>> presentation.add_rule(p, [1, 1], [1])

>>> cong = Congruence(congruence_kind.twosided, p)
>>> fp = to(cong, Return=(FroidurePin,))
>>> fp = to(cong, rtype=(FroidurePin,))
>>> fp.run()

>>> fp.size() == cong.number_of_classes()
Expand Down Expand Up @@ -121,7 +121,7 @@ This function throws a :any:`LibsemigroupsError` if the
>>> presentation.add_rule(p, 'ef', 'dg')

>>> k = Kambites(congruence_kind.twosided, p)
>>> fp = to(k, Return=(FroidurePin,))
>>> fp = to(k, rtype=(FroidurePin,))
>>> fp.enumerate(100)

>>> fp.current_size() == 8205
Expand Down Expand Up @@ -165,7 +165,7 @@ This function throws a :any:`LibsemigroupsError` if ``kb.kind()`` is not
>>> presentation.add_rule(p, [1, 1], [1])

>>> kb = KnuthBendix(congruence_kind.twosided, p)
>>> fp = to(kb, Return=(FroidurePin,))
>>> fp = to(kb, rtype=(FroidurePin,))
>>> fp.run()

>>> fp.size() == kb.number_of_classes()
Expand Down Expand Up @@ -209,7 +209,7 @@ This function throws a :any:`LibsemigroupsError` if ``tc.kind()`` is not
>>> presentation.add_rule(p, [1, 1], [1])

>>> tc = ToddCoxeter(congruence_kind.twosided, p)
>>> fp = to(tc, Return=(FroidurePin,))
>>> fp = to(tc, rtype=(FroidurePin,))
>>> fp.run()

>>> fp.size() == tc.number_of_classes()
Expand Down Expand Up @@ -286,7 +286,7 @@ corresponding :math:`f`.
... w, # wg
... 1, # first
... 2, # last
... Return=(FroidurePin,)
... rtype=(FroidurePin,)
... )
>>> fp.run()

Expand Down
8 changes: 4 additions & 4 deletions docs/source/main-algorithms/knuth-bendix/to-knuth-bendix.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ the semigroup defined by *tc*.
>>> kb = to(
... congruence_kind.twosided, # knd
... tc, # tc
... Return=(KnuthBendix,)
... rtype=(KnuthBendix,)
... )
>>> kb.run()

Expand Down Expand Up @@ -132,7 +132,7 @@ the semigroup defined by *tc*.
>>> kb = to(
... congruence_kind.twosided, # knd
... tc, # tc
... Return=(KnuthBendix, 'RewriteFromLeft')
... rtype=(KnuthBendix, 'RewriteFromLeft')
... )
>>> kb.run()

Expand Down Expand Up @@ -169,7 +169,7 @@ Additionally, specify one of the following for *Return*:

This function converts a :any:`FroidurePin` object *fpb* to a :any:`KnuthBendix`
object with the word type and rewriter as specified above. This is done using
the presentation obtained from ``to(fpb, Return=(Presentation, Word)`` where
the presentation obtained from ``to(fpb, rtype=(Presentation, Word)`` where
``Word`` is either ``str`` or ``list[int]``.

This returned :any:`KnuthBendix` object represents the trivial congruence over
Expand All @@ -196,7 +196,7 @@ the semigroup defined by *fpb*.
>>> kb = to(
... congruence_kind.twosided, # knd
... S, # tc
... Return=(KnuthBendix, list[int], 'RewriteFromLeft')
... rtype=(KnuthBendix, list[int], 'RewriteFromLeft')
... )
>>> kb.run()

Expand Down
4 changes: 2 additions & 2 deletions docs/source/main-algorithms/todd-coxeter/to-todd-coxeter.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ This will throw a :any:`LibsemigroupsError` if *wg* is not the
... congruence_kind.twosided, # knd
... S, # fpb
... S.right_cayley_graph(), # wg
... Return=(ToddCoxeter, str),
... rtype=(ToddCoxeter, str),
... )

>>> tc.run()
Expand Down Expand Up @@ -141,7 +141,7 @@ This will throw a :any:`LibsemigroupsError` if either:
>>> tc = to(
... congruence_kind.twosided, # knd
... kb, # kb
... Return=(ToddCoxeter,)
... rtype=(ToddCoxeter,)
... )
>>> tc.run()

Expand Down
18 changes: 12 additions & 6 deletions src/cong-common.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,9 +72,11 @@ namespace libsemigroups {

fmt::format_to(std::back_inserter(result),
fmt_string,
"detail"_a = extra_doc.detail,
"example"_a = extra_doc.example,
"name"_a = name,
"detail"_a = extra_doc.detail,
"example"_a = extra_doc.example,
"extra_kwargs"_a = extra_doc.extra_kwargs,
"extra_kwargs_doc"_a = extra_doc.extra_kwargs_doc,
"name"_a = name,
"only_document_once"_a
= extra_doc.only_document_once ? only_doc_once : "",
"raises"_a = extra_doc.raises,
Expand All @@ -92,11 +94,15 @@ namespace libsemigroups {
doc extra_doc) {
thing.def(py::init<>(),
make_doc(R"pbdoc(
:sig=() -> None:
:sig=(word: type{extra_kwargs}) -> None:
{only_document_once}

Default constructor. This function default constructs an
uninitialised :any:`{name}` instance.
Default constructor.

This function default constructs an uninitialised :any:`{name}` instance.

:Keyword Arguments:
* **word** (*type*) -- the type of words to use, must be either ``str`` or ``list[int]``{extra_kwargs_doc}

{detail}
)pbdoc",
Expand Down
4 changes: 3 additions & 1 deletion src/cong-common.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,10 +33,12 @@ namespace libsemigroups {
// declared below.
struct doc {
std::string_view detail = "";
std::string_view example = "";
std::string_view extra_kwargs = "";
std::string_view extra_kwargs_doc = "";
bool only_document_once = false;
std::string_view raises = "";
std::string_view var = "";
std::string_view example = "";
};

////////////////////////////////////////////////////////////////////////
Expand Down
15 changes: 10 additions & 5 deletions src/knuth-bendix.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,12 @@ nested class :any:`KnuthBendix.options`.

////////////////////////////////////////////////////////////////////////

def_construct_default(thing, "KnuthBendix");
def_construct_default(
thing,
"KnuthBendix",
doc{.extra_kwargs = ", rewriter: str", .extra_kwargs_doc = R"pbdoc(
* **rewriter** (*str*) -- the type of rewriter to use, must be either ``"RewriteTrie"`` or ``"RewriteFromLeft"``.)pbdoc"sv});

def_init_default(thing, "KnuthBendix");
def_construct_kind_presentation(thing, "KnuthBendix");
def_init_kind_presentation(thing, "KnuthBendix");
Expand Down Expand Up @@ -117,9 +122,9 @@ the current rules in the :py:class:`KnuthBendix` instance.
// Helper functions - specific to KnuthBendix
////////////////////////////////////////////////////////////////////////

// This does not use def_normal_forms in cong-common.hpp because it does
// not return an Iterator object, and hence has its own implementation
// and doc.
// This does not use def_normal_forms in cong-common.hpp because it
// does not return an Iterator object, and hence has its own
// implementation and doc.
m.def(
"knuth_bendix_normal_forms",
[](KnuthBendix_& ci) { return congruence_common::normal_forms(ci); },
Expand Down Expand Up @@ -336,7 +341,7 @@ Copy a :any:`NormalFormRange` object.
});
thing.def("next", [](NormalFormRange& nfr) { nfr.next(); });
} // bind_normal_form_range
} // namespace
} // namespace

template <typename Word>
void bind_redundant_rule(py::module& m) {
Expand Down
12 changes: 6 additions & 6 deletions src/libsemigroups_pybind11/detail/congruence_common.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ def __init__(self: Self, *args, wrong_num_args_msg="", **kwargs) -> None:
# super().__init__ checks if there are unexpected kwargs, sets up
# _cxx_type_to_py_template_params, and sets _cxx_obj if
# the unique argument is a cxx_obj of type in _all_wrapped_cxx_types
super().__init__(*args, optional_kwargs="Word")
super().__init__(*args, optional_kwargs=("word",), **kwargs)
if _to_cxx(self) is not None:
# constructed from args[0] of type belonging to _all_wrapped_cxx_types
return
Expand All @@ -44,17 +44,17 @@ def __init__(self: Self, *args, wrong_num_args_msg="", **kwargs) -> None:
if len(args) != 0 and len(kwargs) != 0:
if len(wrong_num_args_msg) == 0:
wrong_num_args_msg = (
'expected 2 positional arguments or 1 keyword arguments ("Word") '
'expected 2 positional arguments or 1 keyword arguments ("word",) '
f"but found {len(args)} and {len(kwargs)}"
)
raise TypeError(wrong_num_args_msg)
if len(args) == 0:
if kwargs["Word"] not in (str, list[int]):
if kwargs["word"] not in (str, list[int]):
raise ValueError(
'expected the keyword argument "Word" to be "str" or "list[int]" '
f"but found {kwargs['Word']}"
'expected the keyword argument "word" to be "str" or "list[int]" '
f"but found {kwargs['word']}"
)
self.py_template_params = (kwargs["Word"],)
self.py_template_params = (kwargs["word"],)
elif not isinstance(args[0], _congruence_kind):
raise TypeError(
f"expected the 1st argument to be congruence_kind but found {type(args[0])}"
Expand Down
Loading