cutienator 0.0.1.dev0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. cutienator/__init__.py +44 -0
  2. cutienator/_cpp_addr.py +84 -0
  3. cutienator/_cpp_box.py +23 -0
  4. cutienator/_cute_load_hook.py +159 -0
  5. cutienator/_cute_mixin.py +166 -0
  6. cutienator/_cute_overload.py +285 -0
  7. cutienator/_cute_space.py +727 -0
  8. cutienator/_header_descriptor.py +4 -0
  9. cutienator/_meta_cute.py +444 -0
  10. cutienator/_q_binding_storage.py +101 -0
  11. cutienator/_q_event.py +185 -0
  12. cutienator/_q_meta_object.py +118 -0
  13. cutienator/_q_object.py +582 -0
  14. cutienator/_q_thread.py +106 -0
  15. cutienator/_q_widget.py +80 -0
  16. cutienator/_ugly.py +296 -0
  17. cutienator/_wait.py +303 -0
  18. cutienator/_waiting_overload.py +261 -0
  19. cutienator/example/__init__.py +21 -0
  20. cutienator/example/__main__.py +67 -0
  21. cutienator/example/_calls.py +107 -0
  22. cutienator/occult/__init__.py +27 -0
  23. cutienator/occult/__main__.py +50 -0
  24. cutienator/occult/_base_meta_ugly.py +29 -0
  25. cutienator/occult/_build.py +561 -0
  26. cutienator/occult/_cognito_warning.py +35 -0
  27. cutienator/occult/_declaration.py +572 -0
  28. cutienator/occult/_header.py +710 -0
  29. cutienator/occult/_ritual.py +19 -0
  30. cutienator/occult/_rituals.py +594 -0
  31. cutienator/occult/_shared_object.py +292 -0
  32. cutienator/occult/_symbol.py +162 -0
  33. cutienator/occult/rituals/q_event.cpp +70 -0
  34. cutienator/occult/rituals/q_meta_object.cpp +173 -0
  35. cutienator/occult/rituals/q_object.cpp +178 -0
  36. cutienator/trial/__init__.py +25 -0
  37. cutienator/trial/__main__.py +59 -0
  38. cutienator/trial/_judge.py +589 -0
  39. cutienator/trial/_q_object_trials.py +38 -0
  40. cutienator/trial/_trial.py +495 -0
  41. cutienator/trial/_verdict.py +332 -0
  42. cutienator-0.0.1.dev0.dist-info/METADATA +33 -0
  43. cutienator-0.0.1.dev0.dist-info/RECORD +46 -0
  44. cutienator-0.0.1.dev0.dist-info/WHEEL +5 -0
  45. cutienator-0.0.1.dev0.dist-info/licenses/LICENSE +201 -0
  46. cutienator-0.0.1.dev0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,80 @@
1
+ """
2
+ QWidget binding of the Qt C++
3
+ """
4
+ # Apache-2.0 license
5
+ # Copyright (c) 2026 Asger Jon Vistisen
6
+ from __future__ import annotations
7
+
8
+ from typing import TYPE_CHECKING
9
+
10
+ from worktoy.mcls import BaseObject
11
+
12
+ from . import MetaCute, CppAddr
13
+
14
+ if TYPE_CHECKING: # pragma: no cover, no mutate
15
+ from typing import Any
16
+
17
+
18
+ class QWidget(BaseObject, metaclass=MetaCute):
19
+ """
20
+ QWidget binding of the Qt C++
21
+ """
22
+
23
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
24
+ # STATIC METHODS # # # # # # # # # # # # # # # # # # # # # # # # # # # #
25
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
26
+
27
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
28
+ # NAMESPACE # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
29
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
30
+
31
+ # Class Variables
32
+
33
+ # Fallback Variables
34
+
35
+ # Private Variables
36
+
37
+ # Public Variables
38
+ address: CppAddr[int] = CppAddr()
39
+
40
+ # Virtual Variables
41
+
42
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
43
+ # GETTERS # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
44
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
45
+
46
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
47
+ # SETTERS # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
48
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
49
+
50
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
51
+ # NOTIFIERS # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
52
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
53
+
54
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
55
+ # Python API # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
56
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
57
+
58
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
59
+ # CONSTRUCTORS # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
60
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
61
+
62
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
63
+ # DOMAIN SPECIFIC # # # # # # # # # # # # # # # # # # # # # # # # # # # #
64
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
65
+
66
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
67
+ # OPTIONAL METHODS # # # # # # # # # # # # # # # # # # # # # # # # # # #
68
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
69
+
70
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
71
+ # REQUIRED METHODS # # # # # # # # # # # # # # # # # # # # # # # # # # #
72
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
73
+
74
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
75
+ # PARENT METHODS # # # # # # # # # # # # # # # # # # # # # # # # # # # #
76
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
77
+
78
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
79
+ # PUBLIC METHODS # # # # # # # # # # # # # # # # # # # # # # # # # # # #
80
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
cutienator/_ugly.py ADDED
@@ -0,0 +1,296 @@
1
+ """
2
+ Ugly encapsulates the C++ representation of something cute.
3
+ """
4
+ # Apache-2.0 license
5
+ # Copyright (c) 2026 Asger Jon Vistisen
6
+ from __future__ import annotations
7
+
8
+ import weakref
9
+ from typing import TYPE_CHECKING
10
+
11
+ from worktoy.waitaminute import MissingVariable, TypeException
12
+
13
+ from .occult import Rituals
14
+
15
+ if TYPE_CHECKING: # pragma: no cover, no mutate
16
+ from typing import Optional, Any
17
+
18
+
19
+ class Ugly:
20
+ """
21
+ Stands for one C++ object on behalf of its cute side: it holds the
22
+ address of the C++ object and runs rituals on it. The cute classes
23
+ reach C++ through this class and nothing else.
24
+
25
+ ugly = Ugly()
26
+ ugly.setAddress(address) # what the creating ritual returned
27
+ ugly.setCuteSide(cute)
28
+ ugly.call(ritualName) # the address is passed for you
29
+ Ugly.at(address) # the Ugly standing for that address
30
+
31
+ Terms
32
+ -----
33
+
34
+ - The address is the number saying where the C++ object is in memory.
35
+ - The cute side is the Python object people use, as a 'QObject'.
36
+ - A ritual is one plainly named function in cutienator's own shared
37
+ object, run through 'Rituals'.
38
+
39
+ You provide
40
+ -----------
41
+
42
+ Two things, each through its setter, when the C++ object is created:
43
+
44
+ - 'setAddress': where the C++ object is. Once only.
45
+ - 'setCuteSide': the cute object this stands behind.
46
+
47
+ What to expect
48
+ --------------
49
+
50
+ - 'call' puts the address first, so a cute class never handles one.
51
+ - 'Ugly.at' turns an address that C++ handed back into the Ugly
52
+ standing for it. That is how 'child.parent()' gives the very cute
53
+ object you already hold.
54
+ - An Ugly keeps neither side alive. When its cute object goes, the
55
+ Ugly goes too, and the C++ object is left as it is.
56
+ - Nothing deletes a C++ object yet, and nothing notices when C++
57
+ deletes one. An address held here can therefore go bad.
58
+ """
59
+
60
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
61
+ # STATIC METHODS # # # # # # # # # # # # # # # # # # # # # # # # # # # #
62
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
63
+
64
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
65
+ # NAMESPACE # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
66
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
67
+
68
+ # Class Variables
69
+ # Every Ugly with an address, under that address. Held weakly.
70
+ __by_address__ = weakref.WeakValueDictionary()
71
+
72
+ # Fallback Variables
73
+
74
+ # Private Variables
75
+ __cpp_address__ = None # type: Optional[int]
76
+ __cute_side__ = None # type: Optional[weakref.ref]
77
+
78
+ # Public Variables
79
+
80
+ # Virtual Variables
81
+
82
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
83
+ # GETTERS # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
84
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
85
+
86
+ def getAddress(self) -> int:
87
+ """
88
+ Gives where the C++ object is in memory.
89
+
90
+ Provided by you, through 'setAddress'. Nothing fills it in for you.
91
+
92
+ Raises
93
+ ------
94
+
95
+ MissingVariable
96
+ 'setAddress' has not been called on this Ugly.
97
+ """
98
+ if self.__cpp_address__ is None:
99
+ raise MissingVariable(self, '__cpp_address__', int)
100
+ return self.__cpp_address__
101
+
102
+ def getCuteSide(self) -> Any:
103
+ """
104
+ Gives the cute object this Ugly stands behind.
105
+
106
+ Provided by you, through 'setCuteSide'. Nothing fills it in for you.
107
+
108
+ Raises
109
+ ------
110
+
111
+ MissingVariable
112
+ 'setCuteSide' has not been called on this Ugly.
113
+
114
+ RuntimeError
115
+ The cute object no longer exists.
116
+ """
117
+ if self.__cute_side__ is None:
118
+ raise MissingVariable(self, '__cute_side__', object)
119
+ cuteSide = self.__cute_side__()
120
+ if cuteSide is None:
121
+ infoSpec = """The cute object this Ugly stood behind no longer
122
+ exists."""
123
+ raise RuntimeError(' '.join(infoSpec.split()))
124
+ return cuteSide
125
+
126
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
127
+ # SETTERS # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
128
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
129
+
130
+ def setAddress(self, address: int) -> None:
131
+ """
132
+ Tells this Ugly where its C++ object is, and lets 'Ugly.at' find it
133
+ by that address.
134
+
135
+ Required before 'call'. It can be called once: an Ugly stands for
136
+ one C++ object for as long as it exists.
137
+
138
+ Parameters
139
+ ----------
140
+
141
+ address : int
142
+ What the ritual creating the C++ object returned. A positive
143
+ whole number.
144
+
145
+ Raises
146
+ ------
147
+
148
+ TypeException
149
+ 'address' is not an 'int'.
150
+
151
+ ValueError
152
+ 'address' is zero or negative, which is no place in memory.
153
+
154
+ RuntimeError
155
+ An address has been set on this Ugly already.
156
+ """
157
+ if isinstance(address, bool) or not isinstance(address, int):
158
+ raise TypeException('address', address, int)
159
+ if address <= 0:
160
+ infoSpec = """An address is a positive whole number, but received
161
+ %d."""
162
+ raise ValueError(' '.join((infoSpec % address).split()))
163
+ if self.__cpp_address__ is not None:
164
+ infoSpec = """This Ugly already stands for the C++ object at %s and
165
+ cannot be moved to %s."""
166
+ info = infoSpec % (hex(self.__cpp_address__), hex(address))
167
+ raise RuntimeError(' '.join(info.split()))
168
+ self.__cpp_address__ = address
169
+ type(self).__by_address__[address] = self
170
+
171
+ def setCuteSide(self, cuteSide: Any) -> None:
172
+ """
173
+ Tells this Ugly which cute object it stands behind.
174
+
175
+ Required before 'getCuteSide'. The cute object is not kept alive by
176
+ this. Calling it again replaces the cute object given before.
177
+
178
+ Parameters
179
+ ----------
180
+
181
+ cuteSide : Any
182
+ The cute object, as a 'QObject'. It must allow weak references,
183
+ which every worktoy object does.
184
+ """
185
+ self.__cute_side__ = weakref.ref(cuteSide)
186
+
187
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
188
+ # NOTIFIERS # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
189
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
190
+
191
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
192
+ # Python API # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
193
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
194
+
195
+ def __str__(self) -> str:
196
+ """Says where the C++ object is, or that no address is set yet."""
197
+ clsName = type(self).__name__
198
+ if self.__cpp_address__ is None:
199
+ return '<%s with no address yet>' % clsName
200
+ where = hex(self.__cpp_address__)
201
+ return '<%s of the C++ object at %s>' % (clsName, where)
202
+
203
+ __repr__ = __str__
204
+
205
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
206
+ # CONSTRUCTORS # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
207
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
208
+
209
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
210
+ # DOMAIN SPECIFIC # # # # # # # # # # # # # # # # # # # # # # # # # # # #
211
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
212
+
213
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
214
+ # OPTIONAL METHODS # # # # # # # # # # # # # # # # # # # # # # # # # # #
215
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
216
+
217
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
218
+ # REQUIRED METHODS # # # # # # # # # # # # # # # # # # # # # # # # # # #
219
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
220
+
221
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
222
+ # PARENT METHODS # # # # # # # # # # # # # # # # # # # # # # # # # # # #
223
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
224
+
225
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
226
+ # PUBLIC METHODS # # # # # # # # # # # # # # # # # # # # # # # # # # # #
227
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
228
+
229
+ @classmethod
230
+ def at(cls, address: int) -> Ugly:
231
+ """
232
+ Gives the Ugly standing for the C++ object at an address.
233
+
234
+ Use it on an address a ritual returned, to get from C++ back to the
235
+ Python side: 'Ugly.at(address).getCuteSide()'.
236
+
237
+ Parameters
238
+ ----------
239
+
240
+ address : int
241
+ An address a ritual returned.
242
+
243
+ Returns
244
+ -------
245
+
246
+ Ugly
247
+ The one Ugly whose 'setAddress' was given that address.
248
+
249
+ Raises
250
+ ------
251
+
252
+ LookupError
253
+ No Ugly stands for that address. Either C++ created the object
254
+ itself, or the cute object that stood for it no longer exists.
255
+ """
256
+ try:
257
+ return cls.__by_address__[address]
258
+ except KeyError as keyError:
259
+ infoSpec = """No Ugly stands for the C++ object at %s. Either C++
260
+ created that object itself, or its cute object no longer exists."""
261
+ info = ' '.join((infoSpec % hex(address)).split())
262
+ raise LookupError(info) from keyError
263
+
264
+ def call(self, ritualName: str, *args: Any) -> Any:
265
+ """
266
+ Runs one ritual on the C++ object this Ugly stands for.
267
+
268
+ Parameters
269
+ ----------
270
+
271
+ ritualName : str
272
+ The name of the ritual, as 'Declaration.getRitualName' gives
273
+ it: 'ritual_ZNK7QObject6parentEv'.
274
+
275
+ *args : Any
276
+ What the ritual takes after the address of the object, which is
277
+ put first for you. Another object is passed as its address, from
278
+ 'getAddress', or as 'None' for no object.
279
+
280
+ Returns
281
+ -------
282
+
283
+ Any
284
+ What the ritual returns. An address comes back as an 'int', or
285
+ 'None' when C++ answered with no object.
286
+
287
+ Raises
288
+ ------
289
+
290
+ MissingVariable
291
+ 'setAddress' has not been called on this Ugly.
292
+
293
+ LookupError
294
+ 'Rituals' lists no ritual of that name.
295
+ """
296
+ return Rituals.call(ritualName, self.getAddress(), *args)
cutienator/_wait.py ADDED
@@ -0,0 +1,303 @@
1
+ """
2
+ WAIT stands in a class body for a class that is made later.
3
+ """
4
+ # Apache-2.0 license
5
+ # Copyright (c) 2026 Asger Jon Vistisen
6
+ from __future__ import annotations
7
+
8
+ from typing import TYPE_CHECKING
9
+
10
+ from worktoy.core import Object
11
+ from worktoy.waitaminute import MissingVariable, TypeException
12
+
13
+ if TYPE_CHECKING: # pragma: no cover, no mutate
14
+ from typing import Any, Never, Optional
15
+
16
+
17
+ class WAIT(Object):
18
+ """
19
+ Stands in a class body for a class that is made later, so that the
20
+ body can name that class in '@overload' all the same.
21
+
22
+ class QObject(CuteMixin, metaclass=MetaCute):
23
+
24
+ QThread = WAIT['QThread'] # at the top of the class body
25
+
26
+ @overload(QThread)
27
+ def moveToThread(self, thread: QThread) -> bool:
28
+ ...
29
+
30
+ class QThread(QObject): # later, in a file of its own
31
+ ...
32
+
33
+ QObject().moveToThread(QThread()) # works from here on
34
+
35
+ Why it exists
36
+ -------------
37
+
38
+ Qt has classes that name each other. 'QObject::moveToThread' takes a
39
+ 'QThread', and 'QThread' is built on 'QObject'. In C++ that costs
40
+ nothing: the one line 'class QThread;' says that a class of that name
41
+ is coming. In Python '@overload(QThread)' needs the class itself, and
42
+ 'QThread' cannot be made before 'QObject', which it is built on. One
43
+ of the two is always made too soon. A 'WAIT' is our 'class QThread;'.
44
+
45
+ worktoy has 'THIS' for a class naming itself in its own body. 'WAIT'
46
+ is for a class naming another class that does not exist yet.
47
+
48
+ Terms
49
+ -----
50
+
51
+ - The late class is the class a 'WAIT' stands for: 'QThread' above.
52
+ - The waiting class is the class whose body holds the 'WAIT':
53
+ 'QObject' above. It is made too soon to name the late class.
54
+ - A waiting signature is a signature of '@overload' with a 'WAIT' in
55
+ it: '(QThread,)' above.
56
+
57
+ You provide
58
+ -----------
59
+
60
+ - One line per late class, at the top of the body of the waiting
61
+ class, with the name of the late class on both sides:
62
+ 'QThread = WAIT['QThread']'. Or no line at all: write the 'WAIT'
63
+ right into the signature, as '@overload(WAIT['QThread'])', and the
64
+ body gets that line for you.
65
+ - The late class itself, written as any cute class, under that name.
66
+ Nothing has to be called once it is made.
67
+
68
+ What happens, step by step
69
+ --------------------------
70
+
71
+ 1. The body of 'QObject' runs in a 'CuteSpace', the namespace
72
+ 'MetaCute' prepares for every cute class. The line
73
+ 'QThread = WAIT['QThread']' puts a 'WAIT' at the name 'QThread',
74
+ as any attribute of the class.
75
+ 2. The body reads the name 'overload'. 'CuteSpace' answers that read
76
+ itself, with 'CuteOverload', whatever the file imported under the
77
+ name.
78
+ 3. 'CuteOverload' finds the 'WAIT' in the signature. It does not call
79
+ worktoy's 'overload', which refuses anything but a class. It
80
+ leaves a 'WaitingOverload' at the name 'moveToThread', holding the
81
+ signature and the function.
82
+ 4. 'CuteSpace' takes the 'WaitingOverload' out of the body and keeps
83
+ it, with its place among the other signatures of that name.
84
+ worktoy screens the name, as for any overload, and gathers nothing
85
+ from it.
86
+ 5. 'QObject' is made. Its 'moveToThread' has every signature but the
87
+ waiting one. The 'WAIT' at 'QObject.QThread' tells 'MetaCute' that
88
+ 'QObject' waits for a class named 'QThread': see 'hookSetName'.
89
+ 6. 'QThread' is made. 'MetaCute' notices the name. It puts the class
90
+ at 'QObject.QThread', has the 'CuteSpace' of 'QObject' put the
91
+ signature back in its place with the class in it, and builds
92
+ 'moveToThread' again for 'QObject' and for every class built on it
93
+ so far.
94
+
95
+ What to expect
96
+ --------------
97
+
98
+ - Before the late class is made, the waiting signature is not there:
99
+ nothing can be an object of a class that does not exist. The other
100
+ signatures of the name work. A name whose every signature waits is
101
+ not on the class at all until then.
102
+ - After, the waiting class, the classes built on it before and after,
103
+ and the late class itself all take the late class, at the place the
104
+ signature was written in. A wrong argument is refused with
105
+ 'DispatchException', as for any signature.
106
+ - Read through the waiting class, the name gives this 'WAIT' until
107
+ the late class is made, and the class from then on. Read through an
108
+ object it raises 'MissingVariable' until then.
109
+ - A late class is recognised by its name alone, as its '__name__'.
110
+ - A 'WAIT' for a class that is made already is settled as the waiting
111
+ class is made.
112
+ - 'MetaCute.getStillWaiting()' names the classes that are waited for
113
+ and not made.
114
+ - A waiting signature needs a function of its own. Stacking it with
115
+ other 'overload' decorators on one function is refused on that
116
+ line, and so is 'overload.flex' with a 'WAIT'.
117
+ - A 'WAIT' is settled for the class whose body binds it, and for no
118
+ other. A class built on 'QObject' that names 'QThread' in a
119
+ signature of its own names a 'WAIT' of its own, by that line or
120
+ right in the signature. A signature naming 'QObject.QThread' is
121
+ refused with 'TypeError' on that line, and the message gives the
122
+ line to write.
123
+ - worktoy is used as it is. Nothing of this changes it.
124
+ """
125
+
126
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
127
+ # STATIC METHODS # # # # # # # # # # # # # # # # # # # # # # # # # # # #
128
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
129
+
130
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
131
+ # NAMESPACE # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
132
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
133
+
134
+ # Class Variables
135
+
136
+ # Fallback Variables
137
+
138
+ # Private Variables
139
+ __waiting_name__: Optional[str] = None
140
+
141
+ # Public Variables
142
+
143
+ # Virtual Variables
144
+
145
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
146
+ # GETTERS # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
147
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
148
+
149
+ def getWaitingName(self) -> str:
150
+ """
151
+ Gives the name of the late class, as 'QThread'.
152
+
153
+ Provided by you, between the brackets of 'WAIT['QThread']'. There
154
+ is no setter: a 'WAIT' waits for one class for as long as it exists.
155
+
156
+ Raises
157
+ ------
158
+
159
+ MissingVariable
160
+ This 'WAIT' was made without the brackets, which only code going
161
+ around 'WAIT[...]' can do.
162
+ """
163
+ if self.__waiting_name__ is None:
164
+ raise MissingVariable(self, '__waiting_name__', str)
165
+ return self.__waiting_name__
166
+
167
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
168
+ # SETTERS # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
169
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
170
+
171
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
172
+ # NOTIFIERS # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
173
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
174
+
175
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
176
+ # Python API # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
177
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
178
+
179
+ @classmethod
180
+ def __class_getitem__(cls, lateClassName: str) -> WAIT:
181
+ """
182
+ Makes a 'WAIT' for one late class: 'WAIT['QThread']'.
183
+
184
+ This is the only way to make one. Calling 'WAIT(...)' is not it.
185
+
186
+ Parameters
187
+ ----------
188
+
189
+ lateClassName : str
190
+ The name of the late class, exactly as its class statement will
191
+ have it: 'QThread' for 'class QThread(QObject)'.
192
+
193
+ Returns
194
+ -------
195
+
196
+ WAIT
197
+ A new 'WAIT', to be bound in a class body to that same name.
198
+
199
+ Raises
200
+ ------
201
+
202
+ TypeException
203
+ 'lateClassName' is not text.
204
+
205
+ ValueError
206
+ 'lateClassName' is no name a class could have, as '' or '2x'.
207
+ """
208
+ if not isinstance(lateClassName, str):
209
+ raise TypeException('lateClassName', lateClassName, str)
210
+ if not lateClassName.isidentifier():
211
+ infoSpec = """'WAIT' takes the name of a class between its
212
+ brackets, as WAIT['QThread'], but received '%s'."""
213
+ raise ValueError(' '.join((infoSpec % lateClassName).split()))
214
+ self = object.__new__(cls)
215
+ object.__setattr__(self, '__waiting_name__', lateClassName)
216
+ return self
217
+
218
+ def __str__(self) -> str:
219
+ """Shows the 'WAIT' as it is written: WAIT['QThread']."""
220
+ return """WAIT['%s']""" % self.getWaitingName()
221
+
222
+ __repr__ = __str__
223
+
224
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
225
+ # CONSTRUCTORS # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
226
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
227
+
228
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
229
+ # DOMAIN SPECIFIC # # # # # # # # # # # # # # # # # # # # # # # # # # # #
230
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
231
+
232
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
233
+ # OPTIONAL METHODS # # # # # # # # # # # # # # # # # # # # # # # # # # #
234
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
235
+
236
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
237
+ # REQUIRED METHODS # # # # # # # # # # # # # # # # # # # # # # # # # # #
238
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
239
+
240
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
241
+ # PARENT METHODS # # # # # # # # # # # # # # # # # # # # # # # # # # # #
242
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
243
+
244
+ def __instance_get__(self, instance: Any, owner: type, **kwargs) -> Never:
245
+ """
246
+ Refuses a read through an object, as 'QObject().QThread', for as
247
+ long as the late class is not made: there is no class to give yet.
248
+
249
+ 'Object.__get__' calls this for every such read, after its hook
250
+ 'hookPreGet', which is why the refusal sits here and not in
251
+ '__get__'. Once the late class is made, the class itself is at the
252
+ name, and this method is never reached again for it.
253
+
254
+ Raises
255
+ ------
256
+
257
+ MissingVariable
258
+ Always. It is an 'AttributeError', so 'hasattr' answers False.
259
+ """
260
+ raise MissingVariable(instance, self.getFieldName(), type)
261
+
262
+ def hookSetName(self, owner: type, name: str, **kwargs) -> None:
263
+ """
264
+ Tells the metaclass of the waiting class that this class waits.
265
+
266
+ 'Object.__set_name__' calls this as the waiting class is made, with
267
+ the waiting class and the name this 'WAIT' is bound to. You never
268
+ call it. From here on 'MetaCute' knows that 'owner' waits at 'name'
269
+ for a class called as 'getWaitingName' says, and settles it when
270
+ that class is made.
271
+
272
+ Parameters
273
+ ----------
274
+
275
+ owner : type
276
+ The waiting class, being made right now.
277
+
278
+ name : str
279
+ The name this 'WAIT' is bound to in the body of 'owner'.
280
+
281
+ Raises
282
+ ------
283
+
284
+ TypeError
285
+ 'owner' is not made by 'MetaCute', so nothing would ever notice
286
+ the late class. A 'WAIT' belongs in the body of a cute class.
287
+ """
288
+ try:
289
+ addWaiting = type.__getattribute__(type(owner), 'addWaiting')
290
+ except AttributeError as attributeError:
291
+ infoSpec = """%s is bound at '%s.%s', and the class '%s' is made by
292
+ '%s', which notices no late class. A 'WAIT' belongs in the body of
293
+ a class made by 'MetaCute'."""
294
+ info = infoSpec % (
295
+ self, owner.__name__, name, owner.__name__,
296
+ type(owner).__name__,
297
+ )
298
+ raise TypeError(' '.join(info.split())) from attributeError
299
+ addWaiting(owner, name, self)
300
+
301
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
302
+ # PUBLIC METHODS # # # # # # # # # # # # # # # # # # # # # # # # # # # #
303
+ # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #