1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
|
# (C) Copyright 2005-2023 Enthought, Inc., Austin, TX
# All rights reserved.
#
# This software is provided without warranty under the terms of the BSD
# license included in LICENSE.txt and may be redistributed only under
# the conditions described in the aforementioned license. The license
# is also available online at http://www.enthought.com/licenses/BSD.txt
#
# Thanks for using Enthought open source!
"""
Index Managers
==============
This module provides a number of classes for efficiently managing the
mapping between different ways of representing indices. To do so, each
index manager provides an intermediate, opaque index object that is
suitable for use in these situations and is guaranteed to have a long
enough life that it will not change or be garbage collected while a C++
object has a reference to it.
The wx DataView classes expect to be given an integer id value that is
stable and can be used to return the parent reference id.
And Qt's ModelView system expects to be given a pointer to an object
that is long-lived (in particular, it will not be garbage-collected
during the lifetime of a QModelIndex) and which can be used to find
the parent object of the current object.
The default representation of an index from the point of view of the
data view infrastructure is a sequence of integers, giving the index at
each level of the hierarchy. DataViewModel classes can then use these
indices to identify objects in the underlying data model.
There are three main classes defined in the module: AbstractIndexManager,
IntIndexManager, and TupleIndexManager.
AbstractIndexManager
An ABC that defines the API
IntIndexManager
An efficient index manager for non-hierarchical data, such as
lists, tables and 2D arrays.
TupleIndexManager
An index manager that handles non-hierarchical data while trying
to be fast and memory efficient.
The two concrete subclasses should be sufficient for most cases, but advanced
users may create their own if for some reason the provided managers do not
work well for a particular situation. Developers who implement this API
need to be mindful of the requirements on the lifetime and identity
constraints required by the various toolkit APIs.
"""
from abc import abstractmethod
from traits.api import ABCHasStrictTraits, Dict, Int, Tuple
#: The singular root object for all index managers.
Root = ()
class AbstractIndexManager(ABCHasStrictTraits):
""" Abstract base class for index managers.
"""
@abstractmethod
def create_index(self, parent, row):
""" Given a parent index and a row number, create an index.
The internal structure of the index should not matter to
consuming code. However obejcts returned from this method
should persist until the reset method is called.
Parameters
----------
parent : index object
The parent index object.
row : int
The position of the resuling index in the parent's children.
Returns
-------
index : index object
The resulting opaque index object.
Raises
------
IndexError
Negative row values raise an IndexError exception.
RuntimeError
If asked to create a persistent index for a parent and row
where that is not possible, a RuntimeError will be raised.
"""
raise NotImplementedError()
@abstractmethod
def get_parent_and_row(self, index):
""" Given an index object, return the parent index and row.
Parameters
----------
index : index object
The opaque index object.
Returns
-------
parent : index object
The parent index object.
row : int
The position of the resuling index in the parent's children.
Raises
------
IndexError
If the Root object is passed as the index, this method will
raise an IndexError, as it has no parent.
"""
raise NotImplementedError()
def from_sequence(self, indices):
""" Given a sequence of indices, return the index object.
The default implementation starts at the root and repeatedly calls
create_index() to find the index at each level, returning the final
value.
Parameters
----------
indices : sequence of int
The row location at each level of the hierarchy.
Returns
-------
index : index object
The persistent index object associated with this sequence.
Raises
------
RuntimeError
If asked to create a persistent index for a sequence of indices
where that is not possible, a RuntimeError will be raised.
"""
index = Root
for row in indices:
index = self.create_index(index, row)
return index
def to_sequence(self, index):
""" Given an index, return the corresponding sequence of row values.
The default implementation repeatedly calls get_parent_and_row()
to walk up the hierarchy and push the row values into the start
of the sequence.
Parameters
----------
index : index object
The opaque index object.
Returns
-------
sequence : tuple of int
The row location at each level of the hierarchy.
"""
result = ()
while index != Root:
index, row = self.get_parent_and_row(index)
result = (row,) + result
return result
@abstractmethod
def from_id(self, id):
""" Given an integer id, return the corresponding index.
Parameters
----------
id : int
An integer object id value.
Returns
-------
index : index object
The persistent index object associated with this id.
"""
raise NotImplementedError()
@abstractmethod
def id(self, index):
""" Given an index, return the corresponding id.
Parameters
----------
index : index object
The persistent index object.
Returns
-------
id : int
The associated integer object id value.
"""
raise NotImplementedError()
def reset(self):
""" Reset any caches and other state.
Resettable traits in subclasses are indicated by having
``can_reset=True`` metadata. This is provided to allow
toolkit code to clear caches to prevent memory leaks when
working with very large tables.
Care should be taken when calling this method, as Qt may
crash if a QModelIndex is referencing an index that no
longer has a reference in a cache.
For some IndexManagers, particularly for those which are flat
or static, reset() may do nothing.
"""
resettable_traits = self.trait_names(can_reset=True)
self.reset_traits(resettable_traits)
class IntIndexManager(AbstractIndexManager):
""" Efficient IndexManager for non-hierarchical indexes.
This is a simple index manager for flat data structures. The
index values returned are either the Root, or simple integers
that indicate the position of the index as a child of the root.
While it cannot handle nested data, this index manager can
operate without having to perform any caching, and so is very
efficient.
"""
def create_index(self, parent, row):
""" Given a parent index and a row number, create an index.
This should only ever be called with Root as the parent.
Parameters
----------
parent : index object
The parent index object.
row : non-negative int
The position of the resulting index in the parent's children.
Returns
-------
index : index object
The resulting opaque index object.
Raises
------
IndexError
Negative row values raise an IndexError exception.
RuntimeError
If the parent is not the Root, a RuntimeError will be raised
"""
if row < 0:
raise IndexError("Row must be non-negative. Got {}".format(row))
if parent != Root:
raise RuntimeError(
"{} cannot create persistent index value for {}.".format(
self.__class__.__name__,
(parent, row)
)
)
return row
def get_parent_and_row(self, index):
""" Given an index object, return the parent index and row.
Parameters
----------
index : index object
The opaque index object.
Returns
-------
parent : index object
The parent index object.
row : int
The position of the resuling index in the parent's children.
Raises
------
IndexError
If the Root object is passed as the index, this method will
raise an IndexError, as it has no parent.
"""
if index == Root:
raise IndexError("Root index has no parent.")
return Root, int(index)
def from_id(self, id):
""" Given an integer id, return the corresponding index.
Parameters
----------
id : int
An integer object id value.
Returns
-------
index : index object
The persistent index object associated with this id.
"""
if id == 0:
return Root
return id - 1
def id(self, index):
""" Given an index, return the corresponding id.
Parameters
----------
index : index object
The persistent index object.
Returns
-------
id : int
The associated integer object id value.
"""
if index == Root:
return 0
return index + 1
class TupleIndexManager(AbstractIndexManager):
#: A dictionary that maps tuples to the canonical version of the tuple.
_cache = Dict(Tuple, Tuple, {Root: Root}, can_reset=True)
#: A dictionary that maps ids to the canonical version of the tuple.
_id_cache = Dict(Int, Tuple, {0: Root}, can_reset=True)
def create_index(self, parent, row):
""" Given a parent index and a row number, create an index.
Parameters
----------
parent : index object
The parent index object.
row : non-negative int
The position of the resulting index in the parent's children.
Returns
-------
index : index object
The resulting opaque index object.
Raises
------
IndexError
Negative row values raise an IndexError exception.
"""
if row < 0:
raise IndexError("Row must be non-negative. Got {}".format(row))
index = (parent, row)
canonical_index = self._cache.setdefault(index, index)
self._id_cache[self.id(canonical_index)] = canonical_index
return canonical_index
def get_parent_and_row(self, index):
""" Given an index object, return the parent index and row.
Parameters
----------
index : index object
The opaque index object.
Returns
-------
parent : index object
The parent index object.
row : int
The position of the resuling index in the parent's children.
Raises
------
IndexError
If the Root object is passed as the index, this method will
raise an IndexError, as it has no parent.
"""
if index == Root:
raise IndexError("Root index has no parent.")
return index
def from_id(self, id):
""" Given an integer id, return the corresponding index.
Parameters
----------
id : int
An integer object id value.
Returns
-------
index : index object
The persistent index object associated with this id.
"""
return self._id_cache[id]
def id(self, index):
""" Given an index, return the corresponding id.
Parameters
----------
index : index object
The persistent index object.
Returns
-------
id : int
The associated integer object id value.
"""
if index == Root:
return 0
canonical_index = self._cache.setdefault(index, index)
return id(canonical_index)
|
