0
# Dictionary and Data Operations
1
2
Comprehensive dictionary utilities including enhanced dict classes with set operations, grouping functions, and data structure manipulation tools.
3
4
## Capabilities
5
6
### Enhanced Dictionary Classes
7
8
UBelt provides several enhanced dictionary classes that extend standard dict functionality with set operations and auto-vivification.
9
10
```python { .api }
11
class UDict(dict):
12
"""
13
Enhanced dictionary with set operations and convenience methods.
14
Supports | & - ^ operators for union, intersection, difference, and symmetric difference.
15
"""
16
def __or__(self, other): ... # Union operator
17
def __and__(self, other): ... # Intersection operator
18
def __sub__(self, other): ... # Difference operator
19
def __xor__(self, other): ... # Symmetric difference operator
20
21
class AutoDict(dict):
22
"""
23
Auto-vivifying dictionary that creates missing intermediate dictionaries.
24
"""
25
def __getitem__(self, key): ...
26
27
class SetDict(dict):
28
"""
29
Dictionary with key-wise set operations on values.
30
"""
31
def union(self, *others): ...
32
def intersection(self, *others): ...
33
def difference(self, *others): ...
34
35
class AutoOrderedDict(collections.OrderedDict):
36
"""
37
Auto-vivifying ordered dictionary.
38
"""
39
def __getitem__(self, key): ...
40
```
41
42
### Dictionary Operations
43
44
Core dictionary manipulation functions for merging, filtering, and transforming dictionaries.
45
46
```python { .api }
47
def dict_union(*args, **kwargs):
48
"""
49
Union of multiple dictionaries.
50
51
Args:
52
*args: Dictionaries to union
53
**kwargs: Additional key-value pairs
54
55
Returns:
56
dict: Combined dictionary
57
"""
58
59
def dict_isect(*args, **kwargs):
60
"""
61
Intersection of dictionaries (common keys).
62
63
Args:
64
*args: Dictionaries to intersect
65
**kwargs: Additional constraints
66
67
Returns:
68
dict: Dictionary with common keys
69
"""
70
71
def dict_diff(dict1, dict2):
72
"""
73
Dictionary difference showing keys that differ.
74
75
Args:
76
dict1 (dict): First dictionary
77
dict2 (dict): Second dictionary
78
79
Returns:
80
dict: Differences between dictionaries
81
"""
82
83
def dict_subset(dict_, keys, default=NoParam):
84
"""
85
Extract subset of dictionary by keys.
86
87
Args:
88
dict_ (dict): Source dictionary
89
keys: Keys to extract
90
default: Default value for missing keys
91
92
Returns:
93
dict: Subset dictionary
94
"""
95
96
def dict_hist(items, weights=None, ordered=False, labels=None):
97
"""
98
Count discrete occurrences (histogram).
99
100
Args:
101
items: Items to count
102
weights: Optional weights for each item
103
ordered (bool): Return OrderedDict if True
104
labels: Custom labels for items
105
106
Returns:
107
dict: Histogram counts
108
"""
109
```
110
111
### Data Grouping and Organization
112
113
Functions for grouping and organizing data structures.
114
115
```python { .api }
116
def group_items(items, key):
117
"""
118
Group items by key function or corresponding list.
119
120
Args:
121
items: Items to group
122
key: Function or list to group by
123
124
Returns:
125
dict: Grouped items
126
"""
127
128
def dzip(items1, items2, cls=dict):
129
"""
130
Zip items into dictionary with broadcasting.
131
132
Args:
133
items1: Keys or first items
134
items2: Values or second items
135
cls: Dictionary class to use
136
137
Returns:
138
dict: Zipped dictionary
139
"""
140
141
def find_duplicates(items, k=2, key=None):
142
"""
143
Find items occurring k+ times.
144
145
Args:
146
items: Items to analyze
147
k (int): Minimum occurrence count
148
key: Key function for item comparison
149
150
Returns:
151
list: Items with k+ occurrences
152
"""
153
154
def named_product(**basis):
155
"""
156
Named cartesian product of keyword arguments.
157
158
Args:
159
**basis: Named sequences to combine
160
161
Returns:
162
list: List of named combinations
163
"""
164
165
def varied_values(dict_list, min_variations=0):
166
"""
167
Find keys with varying values across dictionaries.
168
169
Args:
170
dict_list (list): List of dictionaries
171
min_variations (int): Minimum variations required
172
173
Returns:
174
dict: Keys and their varying values
175
"""
176
```
177
178
### Dictionary Transformation
179
180
Functions for transforming dictionary keys and values.
181
182
```python { .api }
183
def invert_dict(dict_):
184
"""
185
Swap keys and values in dictionary.
186
187
Args:
188
dict_ (dict): Dictionary to invert
189
190
Returns:
191
dict: Inverted dictionary
192
"""
193
194
def map_keys(func, dict_):
195
"""
196
Apply function to dictionary keys.
197
198
Args:
199
func: Function to apply to keys
200
dict_ (dict): Source dictionary
201
202
Returns:
203
dict: Dictionary with transformed keys
204
"""
205
206
def map_vals(func, dict_):
207
"""
208
Apply function to dictionary values.
209
210
Args:
211
func: Function to apply to values
212
dict_ (dict): Source dictionary
213
214
Returns:
215
dict: Dictionary with transformed values
216
"""
217
218
def map_values(func, dict_):
219
"""
220
Alias for map_vals.
221
"""
222
223
def sorted_keys(dict_, key=None, reverse=False):
224
"""
225
Get sorted dictionary keys.
226
227
Args:
228
dict_ (dict): Source dictionary
229
key: Sort key function
230
reverse (bool): Reverse sort order
231
232
Returns:
233
list: Sorted keys
234
"""
235
236
def sorted_vals(dict_, key=None, reverse=False):
237
"""
238
Get sorted dictionary values.
239
240
Args:
241
dict_ (dict): Source dictionary
242
key: Sort key function
243
reverse (bool): Reverse sort order
244
245
Returns:
246
list: Sorted values
247
"""
248
249
def sorted_values(dict_, key=None, reverse=False):
250
"""
251
Alias for sorted_vals.
252
"""
253
```
254
255
### Convenience Aliases
256
257
```python { .api }
258
# Dictionary class aliases
259
udict = UDict # Enhanced dictionary
260
sdict = SetDict # Set-based dictionary
261
ddict = collections.defaultdict # Default dictionary
262
odict = collections.OrderedDict # Ordered dictionary
263
```
264
265
## Usage Examples
266
267
### Enhanced Dictionary Operations
268
269
```python
270
import ubelt as ub
271
272
# UDict with set operations
273
d1 = ub.UDict({'a': 1, 'b': 2, 'c': 3})
274
d2 = ub.UDict({'b': 2, 'c': 4, 'd': 5})
275
276
# Union
277
union = d1 | d2 # {'a': 1, 'b': 2, 'c': 4, 'd': 5}
278
279
# Intersection
280
intersection = d1 & d2 # {'b': 2}
281
282
# AutoDict auto-vivification
283
auto_dict = ub.AutoDict()
284
auto_dict['level1']['level2']['level3'] = 'value' # Creates intermediate dicts
285
```
286
287
### Data Grouping
288
289
```python
290
import ubelt as ub
291
292
# Group items by first letter
293
items = ['apple', 'banana', 'cherry', 'apricot', 'blueberry']
294
grouped = ub.group_items(items, key=lambda x: x[0])
295
# Result: {'a': ['apple', 'apricot'], 'b': ['banana', 'blueberry'], 'c': ['cherry']}
296
297
# Group by corresponding list
298
scores = [85, 92, 78, 85, 90]
299
grades = ['B', 'A', 'C', 'B', 'A']
300
by_grade = ub.group_items(scores, grades)
301
# Result: {'B': [85, 85], 'A': [92, 90], 'C': [78]}
302
```
303
304
### Dictionary Manipulation
305
306
```python
307
import ubelt as ub
308
309
# Dictionary operations
310
dict1 = {'a': 1, 'b': 2, 'c': 3}
311
dict2 = {'b': 2, 'c': 4, 'd': 5}
312
313
# Union multiple dictionaries
314
combined = ub.dict_union(dict1, dict2, {'e': 6})
315
316
# Transform keys and values
317
uppercase_keys = ub.map_keys(str.upper, dict1)
318
doubled_values = ub.map_vals(lambda x: x * 2, dict1)
319
320
# Get histogram of values
321
items = ['a', 'b', 'a', 'c', 'b', 'a']
322
hist = ub.dict_hist(items) # {'a': 3, 'b': 2, 'c': 1}
323
```