rsarray 1.2.10__cp315-cp315-win_amd64.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 (59) hide show
  1. rsarray/__init__.py +12028 -0
  2. rsarray/_core/__init__.py +213 -0
  3. rsarray/_core/_exceptions.py +83 -0
  4. rsarray/_core/_internal.py +331 -0
  5. rsarray/_core/_multiarray_tests.py +129 -0
  6. rsarray/_core/_multiarray_umath.py +121 -0
  7. rsarray/_core/_rational_tests.py +52 -0
  8. rsarray/_core/arrayprint.py +36 -0
  9. rsarray/_core/fromnumeric.py +31 -0
  10. rsarray/_core/function_base.py +84 -0
  11. rsarray/_core/multiarray.py +385 -0
  12. rsarray/_core/numeric.py +28 -0
  13. rsarray/_core/numerictypes.py +233 -0
  14. rsarray/_core/records.py +14 -0
  15. rsarray/_core/shape_base.py +23 -0
  16. rsarray/_core/strings.py +78 -0
  17. rsarray/_core/umath.py +176 -0
  18. rsarray/_dtypes.py +1229 -0
  19. rsarray/_extra.py +6621 -0
  20. rsarray/_typing.py +24 -0
  21. rsarray/array_methods.py +1224 -0
  22. rsarray/array_ops.py +1585 -0
  23. rsarray/char.py +1590 -0
  24. rsarray/exceptions.py +45 -0
  25. rsarray/fft/__init__.py +231 -0
  26. rsarray/io.py +453 -0
  27. rsarray/lib/__init__.py +102 -0
  28. rsarray/lib/_function_base_impl.py +37 -0
  29. rsarray/lib/_index_tricks_impl.py +98 -0
  30. rsarray/lib/_nanfunctions_impl.py +1637 -0
  31. rsarray/lib/_stride_tricks_impl.py +110 -0
  32. rsarray/lib/recfunctions.py +1222 -0
  33. rsarray/lib/stride_tricks.py +106 -0
  34. rsarray/linalg/__init__.py +2603 -0
  35. rsarray/linalg/_linalg.py +91 -0
  36. rsarray/linalg/_pylinalg.py +1008 -0
  37. rsarray/linalg/lapack_lite.py +13 -0
  38. rsarray/ma/__init__.py +92 -0
  39. rsarray/ma/core.py +1385 -0
  40. rsarray/ma/extras.py +711 -0
  41. rsarray/ma/mrecords.py +144 -0
  42. rsarray/math_functions.py +965 -0
  43. rsarray/matlib.py +67 -0
  44. rsarray/num_core.cp315-win_amd64.pyd +0 -0
  45. rsarray/polynomial/__init__.py +148 -0
  46. rsarray/polynomial/_npcompat.py +721 -0
  47. rsarray/polynomial/polynomial.py +1082 -0
  48. rsarray/random/__init__.py +2266 -0
  49. rsarray/random/_distributions.py +773 -0
  50. rsarray/rec.py +207 -0
  51. rsarray/statistics.py +1360 -0
  52. rsarray/strings.py +349 -0
  53. rsarray/typing/__init__.py +26 -0
  54. rsarray-1.2.10.dist-info/METADATA +280 -0
  55. rsarray-1.2.10.dist-info/RECORD +59 -0
  56. rsarray-1.2.10.dist-info/WHEEL +4 -0
  57. rsarray-1.2.10.dist-info/licenses/LICENSE +21 -0
  58. rsarray-1.2.10.dist-info/licenses/NOTICE +7 -0
  59. rsarray-1.2.10.dist-info/sboms/rsarray.cyclonedx.json +2789 -0
@@ -0,0 +1,1222 @@
1
+ # SPDX-License-Identifier: MIT
2
+ """结构化数组辅助函数(lib.recfunctions 的兼容子集)。
3
+
4
+ 实现直接操作 rsarray 结构化数组的纯 Python 记录模型(_dtype_obj / _raw_data),
5
+ 复用顶层模块暴露的内部辅助函数。
6
+ """
7
+
8
+ import math as _math
9
+
10
+ import rsarray as np
11
+
12
+
13
+ # ========== 内部辅助 ==========
14
+
15
+ def _rich_dtype(x):
16
+ """从数组或 dtype-like 取得富 DType。"""
17
+ if isinstance(x, np.DType):
18
+ return x
19
+ d = getattr(x, 'dtype', None)
20
+ if isinstance(d, np.DType):
21
+ return d
22
+ if d is not None:
23
+ return np.dtype(d)
24
+ return np.dtype(x)
25
+
26
+
27
+ def _records(arr):
28
+ """展平结构化数组为记录 tuple 列表(MaskedArray 先解包底层数据)。"""
29
+ data, _mask = _rec_info(arr)
30
+ return np._flatten_records(data._raw_data)
31
+
32
+
33
+ def _default_field(fdt):
34
+ return np._default_field(fdt, np._zero_scalar_for)
35
+
36
+
37
+ def _project_value(ival, in_fdt, out_fdt):
38
+ """按名称将输入字段值投影到输出字段类型(支持嵌套结构)。"""
39
+ if out_fdt.names is not None and in_fdt is not None and in_fdt.names is not None:
40
+ in_names = in_fdt.names
41
+ # 列表推导代替显式 for 循环
42
+ return tuple(
43
+ _project_value(ival[in_names.index(on)], in_fdt[on], out_fdt[on])
44
+ if on in in_names else _default_field(out_fdt[on])
45
+ for on in out_fdt.names
46
+ )
47
+ return np._coerce_field_value(ival, out_fdt)
48
+
49
+
50
+ def _project_record(rec, in_dt, out_dt):
51
+ """从输入记录按名称构造符合 out_dt 的记录,缺失字段用默认值。"""
52
+ in_names = in_dt.names or ()
53
+ # 列表推导代替显式 for 循环
54
+ return tuple(
55
+ _project_value(rec[in_names.index(on)], in_dt[on], out_dt[on])
56
+ if on in in_names else _default_field(out_dt[on])
57
+ for on in out_dt.names
58
+ )
59
+
60
+
61
+ def _iter_flat(v):
62
+ if isinstance(v, (list, tuple)):
63
+ for x in v:
64
+ yield from _iter_flat(x)
65
+ else:
66
+ yield v
67
+
68
+
69
+ def _collect_leaves(val, fdt, out):
70
+ if fdt.names is not None:
71
+ for i, n in enumerate(fdt.names):
72
+ _collect_leaves(val[i], fdt[n], out)
73
+ elif fdt.subdtype is not None:
74
+ base = fdt.subdtype[0]
75
+ shape = fdt.subdtype[1] or ()
76
+ if base.names is not None:
77
+ # 子数组元素是记录:按外层 shape 逐层遍历,不把记录展平成标量
78
+ def _walk(v, shp):
79
+ if not shp:
80
+ for i, n in enumerate(base.names):
81
+ _collect_leaves(v[i], base[n], out)
82
+ else:
83
+ for e in v:
84
+ _walk(e, shp[1:])
85
+ _walk(val, shape)
86
+ else:
87
+ for x in _iter_flat(val):
88
+ _collect_leaves(x, base, out)
89
+ else:
90
+ out.append(val)
91
+
92
+
93
+ def _record_leaves(rec, dt):
94
+ # 列表推导代替显式 for 循环,但需扩展而非追加
95
+ out = []
96
+ for i, n in enumerate(dt.names):
97
+ leaves = []
98
+ _collect_leaves(rec[i], dt[n], leaves)
99
+ out.extend(leaves)
100
+ return out
101
+
102
+
103
+ def _count_leaves(fdt):
104
+ if fdt.names is not None:
105
+ return sum(_count_leaves(fdt[n]) for n in fdt.names)
106
+ if fdt.subdtype is not None:
107
+ base, shape = fdt.subdtype
108
+ # 使用 math.prod 代替显式 for 循环求积
109
+ return _math.prod(shape) * _count_leaves(base)
110
+ return 1
111
+
112
+
113
+ def _build_from_leaves(flat, idx, fdt):
114
+ if fdt.names is not None:
115
+ # 顺序累积 idx,使用列表推导
116
+ vals = []
117
+ for n in fdt.names:
118
+ v, idx = _build_from_leaves(flat, idx, fdt[n])
119
+ vals.append(v)
120
+ return tuple(vals), idx
121
+ if fdt.subdtype is not None:
122
+ base, shape = fdt.subdtype
123
+ # 使用 math.prod 代替显式 for 循环求积
124
+ total = _math.prod(shape)
125
+ elems = []
126
+ for _ in range(total):
127
+ v, idx = _build_from_leaves(flat, idx, base)
128
+ elems.append(v)
129
+ return np._reshape_flat(elems, shape), idx
130
+ return np._coerce_scalar_by_dt(flat[idx], fdt), idx + 1
131
+
132
+
133
+ def _fix_output(output, usemask=False, asrecarray=False):
134
+ if asrecarray:
135
+ output = np._as_recarray(output)
136
+ if usemask:
137
+ output = np.ma.MaskedArray(output)
138
+ return output
139
+
140
+
141
+ # ========== dtype 内省 ==========
142
+
143
+ def get_names(adtype):
144
+ """返回结构化 dtype 的字段名(嵌套字段以嵌套元组表示)。"""
145
+ adtype = _rich_dtype(adtype)
146
+ # 列表推导代替显式 for 循环
147
+ return tuple(
148
+ (name, tuple(get_names(current))) if (current := adtype[name]).names is not None else name
149
+ for name in adtype.names
150
+ )
151
+
152
+
153
+ def get_names_flat(adtype):
154
+ """返回结构化 dtype 的全部字段名(扁平)。"""
155
+ adtype = _rich_dtype(adtype)
156
+ listnames = []
157
+ # 使用 extend + 生成器推导替代嵌套 for 循环
158
+ for name in adtype.names:
159
+ listnames.append(name)
160
+ current = adtype[name]
161
+ if current.names is not None:
162
+ listnames.extend(get_names_flat(current))
163
+ return tuple(listnames)
164
+
165
+
166
+ def flatten_descr(ndtype):
167
+ """将(可能嵌套的)结构化 dtype 展平为 (name, dtype) 列表。"""
168
+ ndtype = _rich_dtype(ndtype)
169
+ names = ndtype.names
170
+ if names is None:
171
+ return (('', ndtype),)
172
+ descr = []
173
+ for field in names:
174
+ typ = ndtype[field]
175
+ if typ.names is not None:
176
+ descr.extend(flatten_descr(typ))
177
+ else:
178
+ descr.append((field, typ))
179
+ return tuple(descr)
180
+
181
+
182
+ def get_fieldstructure(adtype, lastname=None, parents=None):
183
+ """返回字段到其父字段列表的映射。"""
184
+ adtype = _rich_dtype(adtype)
185
+ if parents is None:
186
+ parents = {}
187
+ names = adtype.names
188
+ for name in names:
189
+ current = adtype[name]
190
+ if current.names is not None:
191
+ if lastname:
192
+ parents[name] = [lastname]
193
+ else:
194
+ parents[name] = []
195
+ parents.update(get_fieldstructure(current, name, parents))
196
+ else:
197
+ lastparent = list(parents.get(lastname, []) or [])
198
+ if lastparent:
199
+ lastparent.append(lastname)
200
+ elif lastname:
201
+ lastparent = [lastname]
202
+ parents[name] = lastparent or []
203
+ return parents
204
+
205
+
206
+ # ========== dtype 重排 ==========
207
+
208
+ def _repack_dtype(dt, align, recurse):
209
+ # 列表推导代替显式 for 循环,一次提取 (name, fdt)
210
+ def _process(name):
211
+ fdt = dt.fields[name][0]
212
+ if recurse and fdt.names is not None:
213
+ fdt = _repack_dtype(fdt, align, recurse)
214
+ return name, fdt
215
+
216
+ pairs = [_process(name) for name in dt.names]
217
+ names = [p[0] for p in pairs]
218
+ formats = [p[1] for p in pairs]
219
+ newdt = np._build_struct(names, formats, None, None, None, align)
220
+ # 保留 record 标记(np.dtype((np.record, dt)) 的 .type 语义)
221
+ _ov = getattr(dt, '_type_override', None)
222
+ if _ov is not None:
223
+ try:
224
+ newdt._type_override = _ov
225
+ except Exception:
226
+ pass
227
+ return newdt
228
+
229
+
230
+ def repack_fields(a, align=False, recurse=False):
231
+ """移除结构化 dtype/数组中字段之间的填充(可选按对齐重排)。"""
232
+ if isinstance(a, np.DType):
233
+ if a.names is None:
234
+ return a
235
+ return _repack_dtype(a, align, recurse)
236
+ dt = _rich_dtype(a)
237
+ newdt = _repack_dtype(dt, align, recurse)
238
+ recs = _records(a)
239
+ return np._wrap_structured(newdt, np._reshape_flat(recs, a.shape))
240
+
241
+
242
+ def _rename_dtype(dt, namemapper):
243
+ # 列表推导代替显式 for 循环
244
+ def _process(name):
245
+ newname = namemapper.get(name, name)
246
+ fdt = dt[name]
247
+ if fdt.names is not None:
248
+ fdt = _rename_dtype(fdt, namemapper)
249
+ return newname, fdt
250
+
251
+ pairs = [_process(name) for name in dt.names]
252
+ names = [p[0] for p in pairs]
253
+ formats = [p[1] for p in pairs]
254
+ return np._build_struct(names, formats, None, None, None, dt.isalignedstruct)
255
+
256
+
257
+ def rename_fields(base, namemapper):
258
+ """重命名结构化数组的字段(支持嵌套字段)。"""
259
+ dt = _rich_dtype(base)
260
+ newdt = _rename_dtype(dt, namemapper)
261
+ recs = _records(base)
262
+ return np._wrap_structured(newdt, np._reshape_flat(recs, base.shape))
263
+
264
+
265
+ # ========== 字段增删 ==========
266
+
267
+ def _drop_descr(ndtype, drop_names):
268
+ names = ndtype.names
269
+ # 列表推导:一次提取 (name, fdt_or_sub),过滤掉 drop_names 与 None sub
270
+ def _process(name):
271
+ if name in drop_names:
272
+ return None
273
+ current = ndtype[name]
274
+ if current.names is not None:
275
+ sub = _drop_descr(current, drop_names)
276
+ if sub is None:
277
+ return None
278
+ return (name, sub)
279
+ return (name, current)
280
+
281
+ pairs = [p for p in (_process(name) for name in names) if p is not None]
282
+ if not pairs:
283
+ return None
284
+ newnames = [p[0] for p in pairs]
285
+ newformats = [p[1] for p in pairs]
286
+ return np._build_struct(newnames, newformats, None, None, None, False)
287
+
288
+
289
+ def drop_fields(base, drop_names, usemask=True, asrecarray=False):
290
+ """删除结构化数组的指定字段(支持嵌套字段名)。"""
291
+ if isinstance(drop_names, str):
292
+ drop_names = {drop_names}
293
+ else:
294
+ drop_names = set(drop_names)
295
+ dt = _rich_dtype(base)
296
+ newdt = _drop_descr(dt, drop_names)
297
+ if newdt is None:
298
+ # 顶层字段全部删除:无字段的空结构化数组(数组语义)
299
+ newdt = np._build_struct([], [], None, None, None, False)
300
+ recs = _records(base)
301
+ newrecs = [_project_record(r, dt, newdt) for r in recs]
302
+ output = np._wrap_structured(newdt, np._reshape_flat(newrecs, base.shape))
303
+ return _fix_output(output, usemask=False, asrecarray=asrecarray)
304
+
305
+
306
+ def require_fields(a, required_dtype):
307
+ """返回仅含指定字段的数组,缺失字段以默认值填充,已有字段做类型转换。"""
308
+ newdt = _rich_dtype(required_dtype)
309
+ dt = _rich_dtype(a)
310
+ recs = _records(a)
311
+ newrecs = [_project_record(r, dt, newdt) for r in recs]
312
+ return np._wrap_structured(newdt, np._reshape_flat(newrecs, a.shape))
313
+
314
+
315
+ def recursive_fill_fields(input, output):
316
+ """将 input 的同名字段递归填入 output(就地修改 output 并返回)。"""
317
+ in_dt = _rich_dtype(input)
318
+ out_dt = _rich_dtype(output)
319
+ in_recs = _records(input)
320
+ out_recs = [list(r) for r in _records(output)]
321
+ in_names = in_dt.names or ()
322
+ out_names = out_dt.names
323
+ # 预计算字段索引映射 (out_idx, in_idx, on_name)
324
+ name_pairs = [
325
+ (oi, in_names.index(on), on)
326
+ for oi, on in enumerate(out_names)
327
+ if on in in_names
328
+ ]
329
+ n = min(len(in_recs), len(out_recs))
330
+ # 外层循环仅取字段名/索引,内层列表推导填充记录
331
+ for oi, ii, on in name_pairs:
332
+ in_field_dt = in_dt[on]
333
+ out_field_dt = out_dt[on]
334
+ for k in range(n):
335
+ out_recs[k][oi] = _project_value(in_recs[k][ii], in_field_dt, out_field_dt)
336
+ _out_data, _out_mask = _rec_info(output)
337
+ _out_data._raw_data = np._reshape_flat([tuple(r) for r in out_recs], _out_data.shape)
338
+ return output
339
+
340
+
341
+ # ========== 结构化 <-> 非结构化 ==========
342
+
343
+ def structured_to_unstructured(arr, dtype=None, copy=False, casting='unsafe'):
344
+ """将结构化数组转换为常规(多一维)数组。"""
345
+ _ = casting
346
+ dt = _rich_dtype(arr)
347
+ recs = _records(arr)
348
+ rows = [_record_leaves(r, dt) for r in recs]
349
+ if not tuple(arr.shape):
350
+ # 0-d 结构化:输出形状 = (叶子数,),无行包装(数组语义)
351
+ nested = rows[0] if rows else []
352
+ else:
353
+ nested = np._reshape_flat(rows, arr.shape)
354
+ # 叶子字段 dtype 收集(uniform 判定 + 视图血缘)。
355
+ # 注意:rsarray 把嵌套子数组解析为递归子数组((i4,(2,2)) → (i4,(2,)) 套
356
+ # (2,)),必须递归展开到真正的标量叶子
357
+ leaf_dts = []
358
+
359
+ def _leaves(f, mult):
360
+ if f._names is not None:
361
+ for n in f.names:
362
+ _leaves(f.fields[n][0], mult)
363
+ elif f._subdtype is not None:
364
+ b, s = f._subdtype
365
+ c = 1
366
+ for s2 in (s or ()):
367
+ c *= s2
368
+ _leaves(b, mult * c)
369
+ else:
370
+ leaf_dts.extend([f] * mult)
371
+
372
+ _leaves(dt, 1)
373
+ _uniform = len(set(str(x) for x in leaf_dts)) == 1 and leaf_dts
374
+ if not _uniform and not leaf_dts:
375
+ # 空结构化 dtype(无字段/零叶子)
376
+ if dtype is not None:
377
+ raise NotImplementedError(
378
+ "structured_to_unstructured with dtype for empty "
379
+ "structured arrays is not implemented")
380
+ raise ValueError("Can't convert 0-field structured arrays")
381
+ if dtype is not None:
382
+ out = np.array(nested).astype(dtype)
383
+ elif _uniform:
384
+ # 数组语义:uniform 字段返回原字段 dtype 的视图
385
+ out = np.array(nested, dtype=np._scalar_name_of(leaf_dts[0]))
386
+ else:
387
+ out = np.array(nested)
388
+ if not copy and _uniform:
389
+ # 共享内存的血缘标记(rsarray 记录模型无字节缓冲,用逻辑血缘表达)
390
+ try:
391
+ out._rs_parent = arr
392
+ except Exception:
393
+ pass
394
+ # 子类保持(数组语义:子类输入 → 子类输出,含 copy=True)
395
+ _tp = type(arr)
396
+ if _tp is not np.ndarray and isinstance(arr, np.ndarray):
397
+ if isinstance(arr, np.recarray):
398
+ out = np._as_recarray(out)
399
+ else:
400
+ try:
401
+ out.__class__ = _tp
402
+ except Exception:
403
+ pass
404
+ if not copy:
405
+ try:
406
+ out._rs_parent = arr
407
+ except Exception:
408
+ pass
409
+ return out
410
+
411
+
412
+ def unstructured_to_structured(arr, dtype=None, names=None, **kwargs):
413
+ """将常规数组转换为结构化数组。"""
414
+ _ = kwargs
415
+ if dtype is None and names is not None:
416
+ raise ValueError("either dtype or names must be provided")
417
+ dt = _rich_dtype(dtype)
418
+ a2 = np.asanyarray(arr)
419
+ if a2.ndim == 0:
420
+ raise ValueError(
421
+ "unstructured_to_structured: input must have at least 1 dimension")
422
+ # 数组语义:末轴按叶子数拆为字段,前导形状为记录形状
423
+ nleaves = _count_leaves(dt)
424
+ if nleaves == 0 or a2.shape[-1] == 0:
425
+ raise NotImplementedError(
426
+ "unstructured_to_structured with zero-leaf input is not "
427
+ "implemented")
428
+ if a2.shape[-1] != nleaves:
429
+ raise ValueError(
430
+ f"input shape {a2.shape} last axis must have {nleaves} leaves "
431
+ f"to match dtype")
432
+ a2 = a2.reshape((-1, nleaves))
433
+ rows = a2.tolist()
434
+ outer_shape = a2.shape[:-1]
435
+
436
+ def build(row):
437
+ rec = []
438
+ idx = 0
439
+ for n in dt.names:
440
+ v, idx = _build_from_leaves(row, idx, dt[n])
441
+ rec.append(v)
442
+ return tuple(rec)
443
+
444
+ recs = [build(r) for r in rows]
445
+ out = np._wrap_structured(dt, np._reshape_flat(recs, outer_shape))
446
+ # 视图血缘传递:输入本身带逻辑血缘(如 structured_to_unstructured
447
+ # 的视图)时,输出沿链共享(数组的 shares_memory 语义)
448
+ try:
449
+ if getattr(arr, '_rs_parent', None) is not None:
450
+ out._rs_parent = arr
451
+ except Exception:
452
+ pass
453
+ if not tuple(outer_shape):
454
+ # 0-d 结构化:保持空形状表示(_struct_shape 会把单记录推断成 (1,))
455
+ try:
456
+ out._rs_shape_override = ()
457
+ except Exception:
458
+ pass
459
+ return out
460
+
461
+
462
+ def _flatten_rows(rows):
463
+ """将嵌套的行列表展平到最内层(每行为标量列表)。"""
464
+ if rows and isinstance(rows[0], list) and rows[0] and isinstance(rows[0][0], list):
465
+ out = []
466
+ for r in rows:
467
+ out.extend(_flatten_rows(r))
468
+ return out
469
+ return rows
470
+
471
+
472
+ # ========== 逐字段应用 ==========
473
+
474
+ def apply_along_fields(func, arr):
475
+ """将归约函数沿字段轴应用于结构化数组。"""
476
+ uarr = structured_to_unstructured(arr)
477
+ return func(uarr, axis=-1)
478
+
479
+
480
+ # ========== 合并 / 堆叠 ==========
481
+
482
+ def _scalar_dtype_of(arr):
483
+ d = arr.dtype
484
+ if isinstance(d, np.DType):
485
+ return d
486
+ return np.dtype(d)
487
+
488
+
489
+ def merge_arrays(seqarrays, fill_value=-1, flatten=False, usemask=False,
490
+ asrecarray=False):
491
+ """将多个数组合并为一个结构化数组。"""
492
+ _ = flatten
493
+ # 单数组输入:视为一个元素的序列(数组语义,merge_arrays(x) →
494
+ # 每元素一条单字段记录)
495
+ if hasattr(seqarrays, 'dtype'):
496
+ seqarrays = [seqarrays]
497
+ arrays = list(seqarrays)
498
+ field_specs = [] # (name, fdt, values)
499
+ mask_specs = [] # 与 field_specs 平行:None(无掩码)或叶子级掩码列表
500
+ counter = 0
501
+ for arr in arrays:
502
+ # MaskedArray 输入:解包底层数组(掩码单独收集)
503
+ mflat = None
504
+ if hasattr(arr, '_data') and not hasattr(arr, '_array'):
505
+ mflat = list(arr._mask)
506
+ arr = arr._data
507
+ if not hasattr(arr, 'dtype'):
508
+ arr = np.asarray(arr)
509
+ dt = _rich_dtype(arr)
510
+ if isinstance(dt, np.DType) and dt.names is not None:
511
+ if hasattr(arr, '_raw_data'):
512
+ recs_list = _records(arr)
513
+ else:
514
+ # 记录标量(z[0] 等):单条记录
515
+ recs_list = [tuple(arr)]
516
+ # 嵌套列表推导:一次提取 (name, dt[n], values)
517
+ for i, n in enumerate(dt.names):
518
+ field_specs.append((n, dt[n], [r[i] for r in recs_list]))
519
+ mask_specs.append(mflat)
520
+ else:
521
+ name = 'f%d' % counter
522
+ counter += 1
523
+ vals = arr.tolist()
524
+ if not isinstance(vals, list):
525
+ vals = [vals]
526
+ field_specs.append((name, _scalar_dtype_of(arr), vals))
527
+ mask_specs.append(mflat)
528
+ maxlen = max((len(v) for _, _, v in field_specs), default=0)
529
+ names = [s[0] for s in field_specs]
530
+ formats = [s[1] for s in field_specs]
531
+ newdt = np._build_struct(names, formats, None, None, None, False)
532
+ # 嵌套列表推导:一次生成所有记录
533
+ recs = [
534
+ tuple(np._coerce_field_value(vals[k], fdt) if k < len(vals)
535
+ else np._coerce_field_value(fill_value, fdt)
536
+ for _, fdt, vals in field_specs)
537
+ for k in range(maxlen)
538
+ ]
539
+ output = np._wrap_structured(newdt, recs)
540
+ if usemask:
541
+ # 字段级掩码:输入掩码叶子 + 值不足 maxlen 的行置 True(数组语义)
542
+ import rsarray.ma as _ma
543
+ flat = []
544
+ for k in range(maxlen):
545
+ for (_, _, vals), mf in zip(field_specs, mask_specs):
546
+ if k >= len(vals):
547
+ flat.append(True)
548
+ elif mf is not None and k < len(mf):
549
+ flat.append(bool(mf[k]))
550
+ else:
551
+ flat.append(False)
552
+ out = _ma.MaskedArray(output, mask=flat)
553
+ if asrecarray:
554
+ from rsarray.ma.mrecords import MaskedRecords
555
+ try:
556
+ out.__class__ = MaskedRecords
557
+ except Exception:
558
+ pass
559
+ return out
560
+ return _fix_output(output, usemask=usemask, asrecarray=asrecarray)
561
+
562
+
563
+ def stack_arrays(arrays, defaults=None, usemask=True, asrecarray=False,
564
+ autoconvert=False):
565
+ """将一组结构化数组按字段并集堆叠。"""
566
+ _ = defaults, autoconvert
567
+ if hasattr(arrays, '_array'):
568
+ return arrays
569
+ arrays = list(arrays)
570
+ if len(arrays) == 1:
571
+ return arrays[0]
572
+ if not arrays:
573
+ return np.array([])
574
+ field_order = []
575
+ field_dts = {}
576
+ # 全为无名数组:直接拼接(数组语义,不做字段包装)
577
+ if not any(_rich_dtype(arr).names is not None for arr in arrays):
578
+ return np.concatenate([np.array(a) for a in arrays])
579
+ # 非结构化数组包装成单字段记录:字段名按其在字段并集中的插入
580
+ # 位置命名(数组语义:stack (x, z)→'f0',stack (z, x)→'f2')
581
+ for ai, arr in enumerate(arrays):
582
+ dt = _rich_dtype(arr)
583
+ if dt.names is not None:
584
+ # 使用 for 循环保持字段顺序(dict 去重)
585
+ for n in dt.names:
586
+ field_dts.setdefault(n, []).append(dt[n])
587
+ if n not in field_dts or len(field_dts[n]) == 1:
588
+ field_order.append(n)
589
+ else:
590
+ fname = 'f%d' % len(field_order)
591
+ arrays[ai] = np.array([(v,) for v in arr.tolist()],
592
+ dtype=[(fname, dt)])
593
+ field_dts.setdefault(fname, []).append(dt)
594
+ if fname not in field_order:
595
+ field_order.append(fname)
596
+ # 字段 dtype:autoconvert 时取各来源中最宽者;不一致且未开则 TypeError
597
+ _KIND_RANK = {'b': 0, 'i': 1, 'u': 1, 'f': 2, 'c': 3}
598
+
599
+ def _widen(dts):
600
+ cur = dts[0]
601
+ for d in dts[1:]:
602
+ if str(d) == str(cur):
603
+ continue
604
+ kc = getattr(cur, '_kind', None)
605
+ kd = getattr(d, '_kind', None)
606
+ if kd != kc:
607
+ if _KIND_RANK.get(kd, -1) > _KIND_RANK.get(kc, -1):
608
+ cur = d
609
+ elif getattr(d, 'itemsize', 0) > getattr(cur, 'itemsize', 0):
610
+ cur = d
611
+ return cur
612
+
613
+ names = field_order
614
+ formats = []
615
+ for n in names:
616
+ dts = field_dts[n]
617
+ if len(dts) == 1:
618
+ formats.append(dts[0])
619
+ else:
620
+ _w = _widen(dts)
621
+ if not autoconvert and any(str(d) != str(_w) for d in dts):
622
+ raise TypeError(
623
+ f'incompatible field dtype for {n!r}: '
624
+ f'{[str(d) for d in dts]} (use autoconvert=True)')
625
+ formats.append(_w)
626
+ newdt = np._build_struct(names, formats, None, None, None, False)
627
+ # 逐记录投影到字段并集;缺失字段填默认值并置掩码;MaskedArray
628
+ # 输入的字段级掩码传播到输出(掩码存储为按字段展平)
629
+ out_recs = []
630
+ out_mask = []
631
+ for arr in arrays:
632
+ data, msk = _rec_info(arr)
633
+ dt = _rich_dtype(data)
634
+ in_names = dt.names or ()
635
+ _ni = len(in_names)
636
+ for ri, r in enumerate(_records(data)):
637
+ row, mrow = [], []
638
+ for on in names:
639
+ if on in in_names:
640
+ ii = in_names.index(on)
641
+ row.append(_project_value(
642
+ r[ii], dt[on], newdt[on]))
643
+ mrow.append(bool(msk[ri * _ni + ii]) if msk else False)
644
+ else:
645
+ row.append(_default_field(newdt[on]))
646
+ mrow.append(True)
647
+ out_recs.append(tuple(row))
648
+ out_mask.append(mrow)
649
+ output = np._wrap_structured(newdt, out_recs)
650
+ if usemask:
651
+ import rsarray.ma as _ma
652
+ # 传每记录掩码列表(与 ma.array 结构化掩码构造路径一致)
653
+ return _ma.MaskedArray(output, mask=out_mask)
654
+ return _fix_output(output, usemask=usemask, asrecarray=asrecarray)
655
+
656
+
657
+ # ========== 去重 ==========
658
+
659
+ def _hashable_key(v):
660
+ """把记录值转为可哈希的键(list 递归转 tuple)。"""
661
+ if isinstance(v, list):
662
+ return tuple(_hashable_key(x) for x in v)
663
+ if isinstance(v, tuple):
664
+ return tuple(_hashable_key(x) for x in v)
665
+ return v
666
+
667
+
668
+ def find_duplicates(a, key=None, ignoremask=True, return_index=False):
669
+ """查找结构化(可选掩码)数组中的重复记录。"""
670
+ if hasattr(a, '_data'):
671
+ base = a._data
672
+ mask = list(a._mask)
673
+ else:
674
+ base = a
675
+ mask = None
676
+ dt = _rich_dtype(base)
677
+ recs = _records(base)
678
+ # key 可为顶层字段或嵌套子字段(BA/BB 等):统一按叶子偏移取范围
679
+ nrec = len(recs)
680
+ if mask is None:
681
+ mask = []
682
+ per = 0
683
+ else:
684
+ # 字段级掩码(长度 = 记录数 × 叶子数):按 key 字段的叶子偏移
685
+ # 判定记录掩码(数组语义:key='A' 时只看 A 字段掩码,key=None
686
+ # 看整条记录任一字段)
687
+ per = len(mask) // nrec if nrec else 0
688
+ _offs = {}
689
+ _o = 0
690
+
691
+ def _walk_offs(d):
692
+ nonlocal _o
693
+ for n in d.names:
694
+ f = d.fields[n][0]
695
+ if f._names is not None:
696
+ _start = _o
697
+ _walk_offs(f)
698
+ # 嵌套字段也记录自己的叶子范围(供 key=嵌套字段使用)
699
+ _offs[n] = (_start, _o - _start)
700
+ elif f._subdtype is not None:
701
+ b, s = f._subdtype
702
+ c = 1
703
+ for s2 in (s or ()):
704
+ c *= s2
705
+ if b._names is not None:
706
+ _start = _o
707
+ _walk_offs(b)
708
+ _offs[n] = (_start, _o - _start)
709
+ else:
710
+ _offs[n] = (_o, c)
711
+ _o += c
712
+ else:
713
+ _offs[n] = (_o, 1)
714
+ _o += 1
715
+
716
+ _walk_offs(dt)
717
+
718
+ # 逐记录构造比较键:key 范围内的叶子值 + 对应掩码(叶子顺序 =
719
+ # dtype 字段序 = 掩码序)。ignoremask=True 时相关叶子任一被掩码
720
+ # 即跳过;ignoremask=False 时掩码叶子互相相等、掩码叶子与值
721
+ # 不相等(数组语义——掩码叶子替换为哨兵即可实现)。
722
+ positions = {}
723
+ for i, r in enumerate(recs):
724
+ leaves = []
725
+ if key is None:
726
+ _collect_leaves(r, dt, leaves)
727
+ chunk = mask[i * per:(i + 1) * per] if per else []
728
+ else:
729
+ leaves_full = []
730
+ _collect_leaves(r, dt, leaves_full)
731
+ off, cnt = _offs.get(key, (0, 1))
732
+ leaves = leaves_full[off:off + cnt]
733
+ chunk = mask[i * per + off:i * per + off + cnt] if per else []
734
+ if ignoremask and any(chunk):
735
+ continue
736
+ k = tuple(('__m__',) if m else (_hashable_key(x),)
737
+ for x, m in zip(leaves, chunk))
738
+ positions.setdefault(k, []).append(i)
739
+
740
+ # 生成器推导:从 positions.values() 拉平并排序重复索引
741
+ dup_idx = sorted(i for idxs in positions.values() if len(idxs) > 1 for i in idxs)
742
+ dup_recs = [recs[i] for i in dup_idx]
743
+ dup_arr = np._wrap_structured(dt, dup_recs)
744
+ if hasattr(a, '_data'):
745
+ dup_arr = np.ma.MaskedArray(dup_arr, [mask[i] for i in dup_idx])
746
+ if return_index:
747
+ return (dup_arr, np.array(dup_idx, dtype='int64'))
748
+ return dup_arr
749
+
750
+
751
+ # ---------------------------------------------------------------------------
752
+ # append_fields / assign_fields_by_name / join_by(lib.recfunctions 兼容)
753
+ # ---------------------------------------------------------------------------
754
+
755
+ def _get_fieldspec(adtype):
756
+ """dtype → [(name, dtype, title), ...](lib.recfunctions._get_fieldspec 兼容)。"""
757
+ dt = adtype if hasattr(adtype, 'names') else np.dtype(adtype)
758
+ if dt.names:
759
+ return [(n, dt.fields[n][0],
760
+ dt.fields[n][2] if len(dt.fields[n]) > 2 else None)
761
+ for n in dt.names]
762
+ return [(None, dt, None)]
763
+
764
+
765
+ def _flatten_descr(ndtype):
766
+ """平铺结构化 dtype 的字段(嵌套子字段直接展开,数组语义)。"""
767
+ if ndtype.names is None:
768
+ return [('', ndtype)]
769
+ descr = []
770
+ for name in ndtype.names:
771
+ fdt = ndtype.fields[name][0]
772
+ if fdt.names is not None:
773
+ descr.extend(_flatten_descr(fdt))
774
+ else:
775
+ descr.append((name, fdt))
776
+ return descr
777
+
778
+
779
+ def _zip_descr(seqarrays, flatten=False):
780
+ """由一维数组列表构造记录字段描述(lib.recfunctions._zip_descr 兼容)。
781
+
782
+ flatten=True:各数组 dtype 平铺到字段级(嵌套子字段展开);
783
+ flatten=False:每数组整体作为一个 '' 命名的字段。
784
+ """
785
+ seqarrays = list(seqarrays)
786
+ if len(seqarrays) == 0:
787
+ return []
788
+ if len(np.asarray(seqarrays[0]).shape[1:]) != 0:
789
+ raise ValueError("only 1-dimensional arrays are supported")
790
+ zipped = []
791
+ if flatten:
792
+ for seqarray in seqarrays:
793
+ zipped.extend(_flatten_descr(np.asarray(seqarray).dtype))
794
+ else:
795
+ for seqarray in seqarrays:
796
+ zipped.append(('', np.asarray(seqarray).dtype))
797
+ return np.dtype(zipped)
798
+
799
+
800
+ def _zip_dtype(seqarrays, flatten=False):
801
+ """由一维数组列表构造记录 dtype(lib.recfunctions._zip_dtype 兼容)。"""
802
+ return np.dtype(_zip_descr(seqarrays, flatten=flatten))
803
+
804
+ def _rec_info(a):
805
+ """返回 (底层数据, 平坦掩码列表或 None)。"""
806
+ import rsarray.ma as _ma
807
+ if _ma.isMaskedArray(a):
808
+ return a.data, list(a._mask)
809
+ return a, None
810
+
811
+
812
+ def _append_fields_values(base, names, data, usemask=True, fill_value=-1):
813
+ """数组语义的 append_fields:按字段名 + 值序列追加新字段。
814
+
815
+ 输出行数为 max(len(base), len(data));不足的行以 fill_value 填充
816
+ 并置掩码。base 为普通数组时字段名取 'f0'(兼容)。
817
+ """
818
+ import rsarray
819
+ import rsarray.ma as ma
820
+ if isinstance(names, str):
821
+ names = [names]
822
+ fields_vals = [data]
823
+ else:
824
+ names = list(names)
825
+ fields_vals = [list(f) for f in data]
826
+ # 基数组字段行与掩码(掩码存储为叶子级:记录数 × 每记录叶子数)
827
+ def _leaf_span(d):
828
+ # 返回 [(name, fdt, off, cnt), ...](叶子偏移与数量)
829
+ spans = []
830
+ _o = [0]
831
+
832
+ def walk(dd):
833
+ for n in dd.names:
834
+ f = dd.fields[n][0]
835
+ if getattr(f, '_names', None) is not None:
836
+ walk(f)
837
+ elif getattr(f, '_subdtype', None) is not None:
838
+ _b, _s = f._subdtype
839
+ c = 1
840
+ for s2 in (_s or ()):
841
+ c *= s2
842
+ if getattr(_b, '_names', None) is not None:
843
+ walk(_b)
844
+ else:
845
+ spans.append((n, f, _o[0], c))
846
+ _o[0] += c
847
+ else:
848
+ spans.append((n, f, _o[0], 1))
849
+ _o[0] += 1
850
+
851
+ walk(d)
852
+ return spans
853
+
854
+ b_names_dt = getattr(getattr(base, 'dtype', None), 'names', None)
855
+ if b_names_dt:
856
+ binfo, bmask = _rec_info(base)
857
+ b_names = list(b_names_dt)
858
+ b_specs = [(n, binfo.dtype.fields[n][0]) for n in b_names]
859
+ b_rows = [[binfo[i][n] for n in b_names] for i in range(binfo.shape[0])]
860
+ b_spans = _leaf_span(binfo.dtype)
861
+ _per = len(bmask) // binfo.shape[0] if (bmask and binfo.shape[0]) else 0
862
+ b_masks = []
863
+ for i in range(binfo.shape[0]):
864
+ chunk = bmask[i * _per:(i + 1) * _per] if _per else []
865
+ # 叶子级掩码行:嵌套/子数组字段展开为其叶子
866
+ rowm = []
867
+ for n, f, off, cnt in b_spans:
868
+ if chunk:
869
+ rowm.extend(bool(x) for x in chunk[off:off + cnt])
870
+ else:
871
+ rowm.extend([False] * cnt)
872
+ b_masks.append(rowm)
873
+ else:
874
+ b_names = ['f0']
875
+ b_specs = [('f0', base.dtype)]
876
+ b_rows = [[v] for v in base.tolist()]
877
+ b_masks = [[False] for _ in b_rows]
878
+ # 新字段的叶子数(掩码行与叶子一一对应)
879
+ def _n_leaves(fdt):
880
+ if getattr(fdt, '_names', None) is not None:
881
+ return sum(_n_leaves(fdt.fields[n][0]) for n in fdt.names)
882
+ if getattr(fdt, '_subdtype', None) is not None:
883
+ _b, _s = fdt._subdtype
884
+ c = 1
885
+ for s2 in (_s or ()):
886
+ c *= s2
887
+ return c * _n_leaves(_b)
888
+ return 1
889
+ n_out = max([len(b_rows)] + [len(f) for f in fields_vals])
890
+ _new_specs = [(nm, np.array(f if len(f) else [0]).dtype)
891
+ for nm, f in zip(names, fields_vals)]
892
+ # 缺失行/缺失值的填充:嵌套结构/子数组字段不能直接填标量
893
+ # (_coerce_record 会因序列长度不匹配越界),按字段 dtype 取默认结构
894
+ def _pad_val(fdt):
895
+ if (getattr(fdt, '_names', None) is not None
896
+ or getattr(fdt, '_subdtype', None) is not None):
897
+ try:
898
+ return np._default_field(fdt, lambda f: fill_value)
899
+ except Exception:
900
+ pass
901
+ return fill_value
902
+ out_rows, out_mask = [], []
903
+ _new_leaves = [_n_leaves(fdt_i) for _nm, fdt_i in _new_specs]
904
+ for i in range(n_out):
905
+ row, mrow = [], []
906
+ if i < len(b_rows):
907
+ row += b_rows[i]
908
+ mrow += b_masks[i]
909
+ else:
910
+ row += [_pad_val(s[1]) for s in b_specs]
911
+ mrow += [True] * len(b_masks[0]) if b_masks else \
912
+ [True] * sum(c for _, _, _, c in b_spans)
913
+ for (nm, fdt_i, f), _lf in zip(zip(names, _new_specs, fields_vals),
914
+ _new_leaves):
915
+ if i < len(f):
916
+ row.append(f[i])
917
+ mrow.extend([False] * _lf)
918
+ else:
919
+ row.append(_pad_val(fdt_i))
920
+ mrow.extend([True] * _lf)
921
+ out_rows.append(row)
922
+ out_mask.append(mrow)
923
+ out_dtype = list(b_specs) + list(_new_specs)
924
+ arr = rsarray.array(out_rows, dtype=out_dtype)
925
+ if usemask:
926
+ flat = [m for rowm in out_mask for m in rowm]
927
+ return ma.MaskedArray(arr, mask=flat)
928
+ return arr
929
+
930
+
931
+ def append_fields(rec1, rec2=None, dk1=None, dk2=None, usemask=True,
932
+ fill_value=-1, names=None, dtype=None, tobegin=False,
933
+ data=None, as_recarray=False):
934
+ """按关键字段把 rec2 的字段追加到 rec1(append_fields 兼容)。
935
+
936
+ 2.x 语义:append_fields(base, names, data=None, fill_value=-1,
937
+ usemask=True, as_recarray=False)——第二位置参数是字段名,data 是
938
+ 各字段的值序列;输出行数为 max(len(base), len(data)),不足的行以
939
+ fill_value 填充并掩码。
940
+ 旧签名(按关键字段合并记录数组,dk1/dk2)保持兼容。
941
+ """
942
+ import rsarray
943
+ import rsarray.ma as ma
944
+ if data is not None:
945
+ # 形式:第二位置参数是字段名,data 是字段值序列
946
+ if names is None:
947
+ names = rec2
948
+ rec2 = data
949
+ return _append_fields_values(rec1, names, rec2, usemask=usemask,
950
+ fill_value=fill_value)
951
+ dk1 = list(dk1) if dk1 else []
952
+ dk2 = list(dk2) if dk2 else []
953
+ data1, mask1 = _rec_info(rec1)
954
+ data2, mask2 = _rec_info(rec2)
955
+ n1 = data1.dtype.names or ()
956
+ n2 = data2.dtype.names or ()
957
+ add_names = [n for n in n2 if n not in n1]
958
+ out_names = list(n1) + add_names if not tobegin else add_names + list(n1)
959
+
960
+ idx = {}
961
+ for j in range(data2.shape[0]):
962
+ key = tuple(data2[j][k] for k in dk2) if dk2 else j
963
+ idx.setdefault(key, []).append(j)
964
+
965
+ out_rows, out_mask = [], []
966
+ for i in range(data1.shape[0]):
967
+ row1 = data1[i]
968
+ key = tuple(row1[k] for k in dk1) if dk1 else i
969
+ j = idx.get(key, [None])[0]
970
+ vals, ms = {}, {}
971
+ for k, n in enumerate(n1):
972
+ vals[n] = row1[n]
973
+ ms[n] = (mask1[i * len(n1) + k] if mask1 else False)
974
+ if j is not None:
975
+ row2 = data2[j]
976
+ for k, n in enumerate(n2):
977
+ if n in add_names:
978
+ vals[n] = row2[n]
979
+ ms[n] = (mask2[j * len(n2) + k] if mask2 else False)
980
+ else:
981
+ for n in add_names:
982
+ vals[n] = fill_value
983
+ ms[n] = True
984
+ out_rows.append([vals[n] for n in out_names])
985
+ out_mask.append([ms[n] for n in out_names])
986
+
987
+ out_dtype = [(n, (data1.dtype.fields[n][0] if n in n1
988
+ else data2.dtype.fields[n][0])) for n in out_names]
989
+ arr = rsarray.array(out_rows, dtype=out_dtype)
990
+ if usemask:
991
+ flat = [m for row in out_mask for m in row]
992
+ return ma.MaskedArray(arr, mask=flat)
993
+ return arr
994
+
995
+
996
+ def assign_fields_by_name(rec1, rec2, usemask=True, overwrite=False,
997
+ extra_fields='drop', zero_unassigned=True):
998
+ """按字段名把 rec2 的值赋给 rec1(第 i 行 ↔ 第 i 行,兼容)。
999
+
1000
+ 原地写回 rec1 中与 rec2 同名的字段(嵌套结构按字段名递归);
1001
+ rec1 独有字段:zero_unassigned=True(默认)清零,False 保留原值。
1002
+ rec2 独有字段按 extra_fields 丢弃('drop')。
1003
+ """
1004
+ import rsarray
1005
+ n1 = getattr(getattr(rec1, 'dtype', None), 'names', None)
1006
+ n2 = getattr(getattr(rec2, 'dtype', None), 'names', None)
1007
+ if n1 is None:
1008
+ # 非结构化数组(含 0-d):整体赋值(测试的 unstructured 路径)
1009
+ try:
1010
+ rec1[...] = rec2
1011
+ except Exception:
1012
+ pass
1013
+ return rec1
1014
+
1015
+ def _zero_field(arr, name):
1016
+ fdt = arr.dtype.fields[name][0]
1017
+ sub = getattr(fdt, '_names', None)
1018
+ if sub:
1019
+ fv = arr[name]
1020
+ for s in sub:
1021
+ _zero_field(fv, s)
1022
+ else:
1023
+ arr[name] = 0
1024
+
1025
+ for n in n1:
1026
+ if n2 and n in n2:
1027
+ v = rec2[n]
1028
+ fdt = rec1.dtype.fields[n][0]
1029
+ if getattr(fdt, '_names', None) is not None:
1030
+ # 嵌套结构:按字段名递归赋值(子字段视图写回父数组)
1031
+ assign_fields_by_name(rec1[n], v, usemask=usemask,
1032
+ overwrite=overwrite,
1033
+ extra_fields=extra_fields,
1034
+ zero_unassigned=zero_unassigned)
1035
+ else:
1036
+ rec1[n] = v
1037
+ elif zero_unassigned:
1038
+ _zero_field(rec1, n)
1039
+ return rec1
1040
+
1041
+
1042
+ def join_by(left, right, keys, jointype='inner', fill_value=None,
1043
+ r1postfix='1', r2postfix='2', defaults=None, usemask=True,
1044
+ as_recarray=False, lsuffix=None, rsuffix=None,
1045
+ join_type=None):
1046
+ """按键字段联接两个记录数组(SQL 风格,join_by 兼容)。
1047
+
1048
+ jointype: 'inner' / 'left' / 'right' / 'outer'(同 'full')。
1049
+ 重叠的非键字段:左表字段加 r1postfix、右表字段加 r2postfix
1050
+ (默认 '1'/'2')。
1051
+ """
1052
+ import rsarray
1053
+ # 顺序:join_by(key, r1, r2, ...)——第一参数是键,后两个是数组;
1054
+ # 旧顺序 (left, right, keys) 以"首参是数组"识别并保持兼容。
1055
+ if (not hasattr(left, 'dtype') and hasattr(right, 'dtype')
1056
+ and hasattr(keys, 'dtype')):
1057
+ left, right, keys = right, keys, left
1058
+ if join_type is None:
1059
+ join_type = jointype
1060
+ join_type = str(join_type).lower()
1061
+ if join_type == 'outer':
1062
+ join_type = 'full'
1063
+ if join_type == 'leftouter':
1064
+ join_type = 'left'
1065
+ if join_type == 'rightouter':
1066
+ join_type = 'right'
1067
+ dl, ml = _rec_info(left)
1068
+ dr, mr = _rec_info(right)
1069
+ nl = dl.dtype.names or ()
1070
+ nr = dr.dtype.names or ()
1071
+ if isinstance(keys, str):
1072
+ keys = [keys]
1073
+ keys = list(keys)
1074
+ if len(set(keys)) != len(keys):
1075
+ raise ValueError(f"duplicate key field(s): {keys}")
1076
+
1077
+ _lp = lsuffix if lsuffix else (r1postfix if r1postfix is not None else '1')
1078
+ _rp = rsuffix if rsuffix else (r2postfix if r2postfix is not None else '2')
1079
+ left_out = {}
1080
+ for n in nl:
1081
+ if n in nr and n not in keys:
1082
+ left_out[n] = f'{n}{_lp}'
1083
+ else:
1084
+ left_out[n] = n
1085
+ right_out = {}
1086
+ for n in nr:
1087
+ if n in nl and n not in keys:
1088
+ right_out[n] = f'{n}{_rp}'
1089
+ else:
1090
+ right_out[n] = n
1091
+ # spec 项: (输出名, 'l'|'r', 源字段名, fdt)。
1092
+ # 数组语义:键字段排最前(按左表字段顺序,不后缀,只出一次);
1093
+ # 同名非键字段左/右相邻输出(b1,b2,c1,c2);两表同名字段 dtype
1094
+ # 不同时取宽者(如 S5/S10 → S10)。
1095
+ def _wider_dt(dt_l, dt_r):
1096
+ ls_, rs_ = getattr(dt_l, 'itemsize', 0), getattr(dt_r, 'itemsize', 0)
1097
+ return dt_r if getattr(dt_r, '_kind', None) == getattr(
1098
+ dt_l, '_kind', None) and rs_ > ls_ else dt_l
1099
+
1100
+ spec = []
1101
+ for n in nl:
1102
+ if n in keys:
1103
+ _fdt = dl.dtype.fields[n][0]
1104
+ if n in nr:
1105
+ _fdt = _wider_dt(_fdt, dr.dtype.fields[n][0])
1106
+ spec.append((n, 'l', n, _fdt))
1107
+ for n in nl:
1108
+ if n in keys:
1109
+ continue
1110
+ spec.append((left_out[n], 'l', n, dl.dtype.fields[n][0]))
1111
+ if n in nr:
1112
+ spec.append((right_out[n], 'r', n, dr.dtype.fields[n][0]))
1113
+ for n in nr:
1114
+ if n not in nl:
1115
+ spec.append((right_out[n], 'r', n, dr.dtype.fields[n][0]))
1116
+ out_names = [s[0] for s in spec]
1117
+
1118
+ def _key_val(rec, k):
1119
+ # 子数组字段值(ndarray)不可哈希,转为 tuple
1120
+ v = rec[k]
1121
+ if hasattr(v, 'tolist'):
1122
+ t = v.tolist()
1123
+ return tuple(t) if isinstance(t, list) else t
1124
+ return tuple(v) if isinstance(v, list) else v
1125
+
1126
+ idx = {}
1127
+ for j in range(dr.shape[0]):
1128
+ key = tuple(_key_val(dr[j], k) for k in keys)
1129
+ idx.setdefault(key, []).append(j)
1130
+ right_lists = {k: list(v) for k, v in idx.items()}
1131
+ consumed_r, consumed_l = set(), set()
1132
+ out_rows, out_mask = [], []
1133
+
1134
+ # 缺省值:fill_value=None 时按字段 dtype 取类型默认值(值被掩码,
1135
+ # 数组语义:defaults 未给时数值取 0、字符串取 '')
1136
+ def _default_for(fdt):
1137
+ if fill_value is not None:
1138
+ return fill_value
1139
+ k = getattr(fdt, '_kind', None)
1140
+ if k in ('S', 'U'):
1141
+ return ''
1142
+ if k == 'c':
1143
+ return 0j
1144
+ if k in ('i', 'u', 'f', 'b'):
1145
+ return 0
1146
+ return None
1147
+
1148
+ # 字段名重复(如空后缀导致重命名失效)→ ValueError(数组语义)
1149
+ if len(set(out_names)) != len(out_names):
1150
+ dupes = sorted({n for n in out_names if out_names.count(n) > 1})
1151
+ raise ValueError(f'field name(s) duplicated in join result: {dupes}')
1152
+
1153
+ def _emit(i, j):
1154
+ row, mrow = [], []
1155
+ for out_n, side, src_n, fdt in spec:
1156
+ if side == 'l':
1157
+ if i is None:
1158
+ if j is not None and src_n in keys and src_n in nr:
1159
+ # 右未匹配行:键字段值取自右表(数组语义:
1160
+ # 键值来自存在的一侧、未掩码)
1161
+ row.append(dr[j][src_n])
1162
+ mrow.append(mr[j * len(nr) + nr.index(src_n)]
1163
+ if mr else False)
1164
+ else:
1165
+ row.append(_default_for(fdt))
1166
+ mrow.append(True)
1167
+ else:
1168
+ row.append(dl[i][src_n])
1169
+ mrow.append(ml[i * len(nl) + nl.index(src_n)]
1170
+ if ml else False)
1171
+ else:
1172
+ if j is None:
1173
+ row.append(_default_for(fdt))
1174
+ mrow.append(True)
1175
+ else:
1176
+ row.append(dr[j][src_n])
1177
+ mrow.append(mr[j * len(nr) + nr.index(src_n)]
1178
+ if mr else False)
1179
+ out_rows.append(row)
1180
+ out_mask.append(mrow)
1181
+
1182
+ if join_type in ('inner', 'left', 'full'):
1183
+ for i in range(dl.shape[0]):
1184
+ key = tuple(_key_val(dl[i], k) for k in keys)
1185
+ ms = [j for j in right_lists.get(key, []) if j not in consumed_r]
1186
+ if ms:
1187
+ for j in ms:
1188
+ consumed_r.add(j)
1189
+ consumed_l.add(i)
1190
+ _emit(i, j)
1191
+ elif join_type in ('left', 'full'):
1192
+ _emit(i, None)
1193
+ if join_type in ('right', 'full'):
1194
+ for j in range(dr.shape[0]):
1195
+ if j in consumed_r:
1196
+ continue
1197
+ key = tuple(_key_val(dr[j], k) for k in keys)
1198
+ i = next((x for x in range(dl.shape[0])
1199
+ if tuple(_key_val(dl[x], k) for k in keys) == key
1200
+ and x not in consumed_l), None)
1201
+ if i is not None:
1202
+ consumed_l.add(i)
1203
+ _emit(i, j)
1204
+ else:
1205
+ _emit(None, j)
1206
+
1207
+ out_dtype = [(n, fdt) for n, _side, _src, fdt in spec]
1208
+ # 数组语义:join_by 输出按键字段排序(键字段在 spec 最前)
1209
+ _nk = len(keys)
1210
+ if _nk and len(out_rows) > 1:
1211
+ order = sorted(range(len(out_rows)),
1212
+ key=lambda r: tuple(out_rows[r][:_nk]))
1213
+ out_rows = [out_rows[r] for r in order]
1214
+ out_mask = [out_mask[r] for r in order]
1215
+ arr = rsarray.array(out_rows, dtype=out_dtype)
1216
+ import rsarray.ma as ma
1217
+ if usemask and (rsarray.ma.isMaskedArray(left)
1218
+ or rsarray.ma.isMaskedArray(right)
1219
+ or any(any(row) for row in out_mask)):
1220
+ flat = [m for row in out_mask for m in row]
1221
+ return ma.MaskedArray(arr, mask=flat)
1222
+ return arr