Skip to content

Commit 375d256

Browse files
james-d-mitchelljames-d-mitchell
committed
Renovate adapters
1 parent 7bb2fdb commit 375d256

File tree

5 files changed

+205
-78
lines changed

5 files changed

+205
-78
lines changed

‎docs/source/data-structures/adapters/imageleftaction.rst

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
.. Copyright (c) 2024 James Mitchell
2+
3+
Distributed under the terms of the GPL license version 3.
4+
5+
The full license is in the file LICENSE, distributed with this software.
6+
7+
.. currentmodule:: libsemigroups_pybind11
8+
9+
The ImageLeftAction class
10+
==========================
11+
12+
.. autoclass:: ImageLeftAction
13+
:doc-only:
14+
:class-doc-from: class
15+
16+
Contents
17+
--------
18+
19+
.. autosummary::
20+
:signatures: short
21+
22+
~ImageLeftAction
23+
ImageLeftAction.__call__
24+
25+
Full API
26+
--------
27+
28+
.. autoclass:: ImageLeftAction
29+
:members:
30+
:class-doc-from: init
31+
:special-members: __call__

‎docs/source/data-structures/adapters/imagerightaction.rst

Lines changed: 20 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,28 @@
44
55
The full license is in the file LICENSE, distributed with this software.
66
7-
.. currentmodule:: _libsemigroups_pybind11
7+
.. currentmodule:: libsemigroups_pybind11
88

9-
ImageRightAction + ImageLeftAction
10-
==================================
9+
The ImageRightAction class
10+
==========================
1111

12-
.. autoclass:: ImageRightActionPPerm1PPerm1
13-
:members:
14-
:show-inheritance:
12+
.. autoclass:: ImageRightAction
13+
:doc-only:
1514
:class-doc-from: class
1615

17-
.. autoclass:: ImageLeftActionPPerm1PPerm1
16+
Contents
17+
--------
18+
19+
.. autosummary::
20+
:signatures: short
21+
22+
~ImageRightAction
23+
ImageRightAction.__call__
24+
25+
Full API
26+
--------
27+
28+
.. autoclass:: ImageRightAction
1829
:members:
19-
:show-inheritance:
20-
:class-doc-from: class
30+
:class-doc-from: init
31+
:special-members: __call__

‎docs/source/data-structures/adapters/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,5 @@ types.
1818
:maxdepth: 1
1919

2020
imagerightaction
21+
imageleftaction
2122

‎libsemigroups_pybind11/adapters.py

Lines changed: 73 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -33,24 +33,26 @@
3333
CxxWrapper as _CxxWrapper,
3434
to_cxx as _to_cxx,
3535
to_py as _to_py,
36+
copy_cxx_mem_fns as _copy_cxx_mem_fns,
37+
register_cxx_wrapped_type as _register_cxx_wrapped_type,
3638
)
3739

38-
from .tools import ordinal
40+
from .detail.decorators import copydoc as _copydoc
41+
3942
from .transf import PPerm as _PPerm
4043

44+
########################################################################
45+
# The ImageAction protected class
46+
########################################################################
47+
4148

4249
class _ImageAction(_CxxWrapper):
4350
"""
4451
This is a protected base class for ImageRightAction and ImageLeftAction.
52+
See the documentation for more details.
4553
"""
4654

47-
Element = _TypeVar("Element")
48-
Point = _TypeVar("Point")
49-
5055
def __init__(self: _Self, *args, point=None, element=None) -> None:
51-
"""
52-
TODO
53-
"""
5456
super().__init__(
5557
*args,
5658
required_kwargs=("element", "point"),
@@ -71,14 +73,16 @@ def __call__(self: _Self, *args):
7173
return _to_py(_to_cxx(self)(*(_to_cxx(x) for x in args)))
7274

7375

76+
########################################################################
77+
# The ImageRightAction class
78+
########################################################################
79+
80+
7481
class ImageRightAction(_ImageAction):
75-
"""TODO update
76-
Construct a ImageRightAction instance.
82+
Element = _TypeVar("Element")
83+
Point = _TypeVar("Point")
7784

78-
:Keyword Arguments:
79-
* *Element* -- the type of the elements in the action
80-
* *Point* -- the type of the points acted on
81-
"""
85+
__doc__ = _ImageRightActionPPerm1PPerm1.__doc__
8286

8387
_py_template_params_to_cxx_type = {
8488
(_BMat8, _BMat8): _ImageRightActionBMat8BMat8,
@@ -95,15 +99,46 @@ class ImageRightAction(_ImageAction):
9599

96100
_all_wrapped_cxx_types = {*_py_template_params_to_cxx_type.values()}
97101

102+
def __init__(self: _Self, *args, point=None, element=None):
103+
"""
104+
:sig=(self: ImageRightAction, element=None, point=None):
105+
106+
Construct from sample element and sample point.
107+
108+
:Keyword Arguments:
109+
* **element** (*Element*) -- a sample element.
110+
* **point** (*Point*) -- a sample point.
111+
112+
:raises KeyError:
113+
if the action defined by the arguments is not defined.
114+
"""
115+
super.__init__(*args, point=point, element=element)
116+
117+
@_copydoc(_ImageRightActionPPerm1PPerm1.__call__)
118+
def __call__(self: _Self, pt: Point, x: Element) -> Point:
119+
return _to_py(_to_cxx(self)(_to_cxx(pt), _to_cxx(x)))
120+
121+
122+
########################################################################
123+
# Copy mem fns from sample C++ type and register types
124+
########################################################################
125+
126+
_copy_cxx_mem_fns(_ImageRightActionPPerm1PPerm1, ImageRightAction)
127+
128+
for _type in ImageRightAction._py_template_params_to_cxx_type.values():
129+
_register_cxx_wrapped_type(_type, ImageRightAction)
130+
131+
132+
########################################################################
133+
# The ImageLeftAction class
134+
########################################################################
135+
98136

99137
class ImageLeftAction(_ImageAction):
100-
"""TODO update
101-
Construct a ImageLeftAction instance.
138+
Element = _TypeVar("Element")
139+
Point = _TypeVar("Point")
102140

103-
:Keyword Arguments:
104-
* *Element* -- the type of the elements in the action
105-
* *Point* -- the type of the points acted on
106-
"""
141+
__doc__ = _ImageLeftActionPPerm1PPerm1.__doc__
107142

108143
_py_template_params_to_cxx_type = {
109144
(_BMat8, _BMat8): _ImageLeftActionBMat8BMat8,
@@ -118,3 +153,22 @@ class ImageLeftAction(_ImageAction):
118153
)
119154

120155
_all_wrapped_cxx_types = {*_py_template_params_to_cxx_type.values()}
156+
157+
def __init__(self: _Self, *args, point=None, element=None):
158+
"""
159+
:sig=(self: ImageLeftAction, element=None, point=None):
160+
161+
Construct from sample element and sample point.
162+
163+
:Keyword Arguments:
164+
* **element** (*Element*) -- a sample element.
165+
* **point** (*Point*) -- a sample point.
166+
167+
:raises KeyError:
168+
if the action defined by the arguments is not defined.
169+
"""
170+
super.__init__(*args, point=point, element=element)
171+
172+
@_copydoc(_ImageLeftActionPPerm1PPerm1.__call__)
173+
def __call__(self: _Self, pt: Point, x: Element) -> Point:
174+
return _to_py(_to_cxx(self)(_to_cxx(pt), _to_cxx(x)))

‎src/adapters.cpp

Lines changed: 80 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -42,22 +42,9 @@ namespace libsemigroups {
4242
R"pbdoc(
4343
Adapter for computing the image of a point under a right action.
4444
45-
:Keyword Arguments:
46-
* *Element* -- the type of the elements in the action
47-
* *Point* -- the type of the points acted on
48-
49-
This class provides call operators of the following signatures:
50-
51-
1. ``(res: Point, pt: Point, x: Element)``
52-
2. ``(pt: Point, x: Element)``
53-
54-
In form (1): the call operator changes *res* in-place to contain the
55-
image of the point *pt* under the right action of the element *x*. The
56-
purpose of the 1st parameter is to avoid repeated allocations of memory to hold
57-
temporary points that are discarded soon after they are created.
58-
59-
In form (2): the call operator returns the image of the point *pt* under the
60-
right action of the element *x*.
45+
This class provides a call operator with signature ``(pt: Point, x: Element) ->
46+
Point``, returning the image of the point *pt* under the right action of the
47+
element *x*.
6148
6249
.. doctest::
6350
@@ -78,6 +65,7 @@ right action of the element *x*.
7865
>>> func(_, x)
7966
PPerm([], [], 10)
8067
)pbdoc")
68+
// The next constructor isn't available in python so no doc.
8169
.def(py::init<>())
8270
// The following doesn't yet work because mostly it's not possible to
8371
// change <res> in place.
@@ -86,15 +74,42 @@ right action of the element *x*.
8674
// Point& res,
8775
// Point const& pt,
8876
// Element const& x) -> void { self(res, pt, x); })
89-
.def("__call__",
90-
[](ImageRightAction_ const& self,
91-
Point const& pt,
92-
Element const& x) -> Point {
93-
// Copy pt, to ensure that pt and res have the same degree
94-
Point res = pt;
95-
self(res, pt, x);
96-
return res;
97-
});
77+
.def(
78+
"__call__",
79+
[](ImageRightAction_ const& self,
80+
Point const& pt,
81+
Element const& x) -> Point {
82+
// Copy pt, to ensure that pt and res have the same degree
83+
Point res = pt;
84+
self(res, pt, x);
85+
return res;
86+
},
87+
py::arg("pt"),
88+
py::arg("x"),
89+
R"pbdoc(
90+
:sig=(self: ImageRightAction, pt: Point, x: Element) -> Point:
91+
92+
Return the image of a point acted on by an element.
93+
94+
This call operator returns the image of *pt* acted on by *x*.
95+
96+
:param pt: the point on which to act.
97+
:type pt: Point
98+
99+
:param x: the element doing the acting.
100+
:type x: Element
101+
102+
:returns: The image of *pt* acted on by *x*.
103+
:rtype: Point
104+
105+
:raises TypeError:
106+
If the wrapped C++ type of the sample objects passed via *element* and
107+
*point* are not the same as the wrapped types of the arguments in any
108+
invocation of the call operator. For example, if *point* is ``PPerm([], [],
109+
256)``, then the underlying C++ type uses 8-bit integers to store image
110+
values. So, any partial permutation passed as the 1st argument to the
111+
call operator must be of degree at most ``256``.
112+
)pbdoc");
98113
} // bind_imagerightaction
99114

100115
template <typename Element, typename Point>
@@ -106,22 +121,9 @@ right action of the element *x*.
106121
R"pbdoc(
107122
Adapter for computing the image of a point under a left action.
108123
109-
:Keyword Arguments:
110-
* *Element* -- the type of the elements in the action
111-
* *Point* -- the type of the points acted on
112-
113-
This class provides call operators of the following signatures:
114-
115-
1. ``(res: Point, pt: Point, x: Element)``
116-
2. ``(pt: Point, x: Element)``
117-
118-
In form (1): the call operator changes *res* in-place to contain the
119-
image of the point *pt* under the left action of the element *x*. The
120-
purpose of the 1st parameter is to avoid repeated allocations of memory to hold
121-
temporary points that are discarded soon after they are created.
122-
123-
In form (2): the call operator returns the image of the point *pt* under the
124-
left action of the element *x*.
124+
This class provides a call operator with signature ``(pt: Point, x: Element) ->
125+
Point``, returning the image of the point *pt* under the left action of the
126+
element *x*.
125127
126128
.. doctest::
127129
@@ -132,6 +134,7 @@ left action of the element *x*.
132134
>>> func(pt, x)
133135
PPerm([2, 3, 6, 9], [2, 3, 6, 9], 10)
134136
)pbdoc")
137+
// The next constructor isn't available in python so no doc.
135138
.def(py::init<>())
136139
// The following doesn't yet work because mostly it's not possible to
137140
// change <res> in place.
@@ -140,15 +143,42 @@ left action of the element *x*.
140143
// Point& res,
141144
// Point const& pt,
142145
// Element const& x) { self(res, pt, x); })
143-
.def("__call__",
144-
[](ImageLeftAction_ const& self,
145-
Point const& pt,
146-
Element const& x) {
147-
// Copy pt, to ensure that pt and res have the same degree
148-
Point res = pt;
149-
self(res, pt, x);
150-
return res;
151-
});
146+
.def(
147+
"__call__",
148+
[](ImageLeftAction_ const& self,
149+
Point const& pt,
150+
Element const& x) {
151+
// Copy pt, to ensure that pt and res have the same degree
152+
Point res = pt;
153+
self(res, pt, x);
154+
return res;
155+
},
156+
py::arg("pt"),
157+
py::arg("x"),
158+
R"pbdoc(
159+
:sig=(self: ImageLeftAction, pt: Point, x: Element) -> Point:
160+
161+
Return the image of a point acted on by an element.
162+
163+
This call operator returns the image of *pt* acted on by *x*.
164+
165+
:param pt: the point on which to act.
166+
:type pt: Point
167+
168+
:param x: the element doing the acting.
169+
:type x: Element
170+
171+
:returns: The image of *pt* acted on by *x*.
172+
:rtype: Point
173+
174+
:raises TypeError:
175+
If the wrapped C++ type of the sample objects passed via *element* and
176+
*point* are not the same as the wrapped types of the arguments in any
177+
invocation of the call operator. For example, if *point* is ``PPerm([], [],
178+
256)``, then the underlying C++ type uses 8-bit integers to store image
179+
values. So, any partial permutation passed as the 1st argument to the
180+
call operator must be of degree at most ``256``.
181+
)pbdoc");
152182
} // bind_imageleftaction
153183

154184
} // namespace

0 commit comments

Comments
 (0)