bigarraylist 0.2.0__py3-none-any.whl

bigarraylist/core/base.py

@@ -0,0 +1,223 @@
+"""BaseBigArrayList：迭代协议 + _fresh_iter + __slots__。
+
+通过 cooperative multiple inheritance 组合各算子 mixin：
+    BaseBigArrayList(_CoreBase, CRUDMixin, StreamMixin, SortMixin, SearchMixin)
+
+各 mixin 只声明方法、不声明字段（避免 __slots__ 多继承冲突），
+通过 self._fresh_iter() 和 len(self) 与 _CoreBase 协作。
+蓄水池抽样 _sample 直接写在 _CoreBase 里（依赖 reservoir_sample 函数即可，无需 mixin）。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator, Iterable, Iterator
+from typing import Any, Generic, TypeVar
+
+from ..algorithms.sample import reservoir_sample
+from ..config import BigArrayConfig
+from ..operators.crud import CRUDMixin
+from ..operators.search import SearchMixin
+from ..operators.sort import SortMixin
+from ..operators.stream import StreamMixin
+
+T = TypeVar("T")
+
+
+class _CoreBase(Generic[T]):
+    """核心：__slots__ + 迭代协议 + _fresh_iter。
+
+    所有算子方法（_append_iter / find / sort / ...）由各 mixin 提供，
+    它们统一通过本类的 _fresh_iter() 和 len(self) 与核心交互，
+    不直接访问 self.__source / self.__len 等私有字段——
+    避免 name mangling 在 mixin 模式下找不到属性。
+
+    继承 Generic[T] 让 T 在本类内被绑定，使 _fresh_iter / __next__ 等方法
+    的返回类型 T 能被 mypy 推导；运行时 Generic 不引入额外开销。
+    """
+
+    __slots__ = ("__config", "__data", "__index", "__len", "__source")
+
+    # 类型标注（mypy 用，运行时被 __slots__ 覆盖）
+    __config: BigArrayConfig
+    __data: Iterator[Any]
+    __index: int
+    __len: int
+    __source: int | Iterable[Any]
+
+    def __init__(self, source: int | Iterable[T], *, config: BigArrayConfig | None = None) -> None:
+        """三种构造方式：
+        - source 是 int：用生成器造 source 个全 0 数据（大数据惰性测试用）
+        - source 是 Sized Iterable（list/tuple 等有 __len__ 的）：直接用其 len
+        - source 是纯 Iterator/Generator（没 len 的）：**必须物化才能知道长度**，
+          大数据场景不推荐——传进来前最好先过 list(...) 或者自己算好长度传 int
+        """
+        # 保存配置（None 用默认）
+        self.__config = config if config is not None else BigArrayConfig.default()
+
+        # 保存原始 source，供重置迭代器用
+        self.__source = source
+        if isinstance(source, int):
+            self.__data = iter(0 for _ in range(source))
+            self.__len = source
+        else:
+            try:
+                # 优先走 __len__ 路径（list/tuple/str 等容器，零物化）
+                data_len = len(source)  # type: ignore[arg-type]
+            except TypeError:
+                # 没 __len__ 的可迭代对象（包括 generator）：必须物化拿长度
+                materialized = list(source)
+                # ✅ 关键修复：source 已在 list() 时耗尽，必须更新 __source 为物化后的 list，
+                # 否则 _fresh_iter() 会返回空迭代器，所有算子产出空数据
+                self.__source = materialized
+                self.__data = iter(materialized)
+                self.__len = len(materialized)
+            else:
+                # 也要兼容 Generator（即使有 __len__ 也不能复用）
+                from collections.abc import Generator as _Gen
+
+                if isinstance(source, _Gen):
+                    materialized = list(source)
+                    self.__source = materialized
+                    self.__data = iter(materialized)
+                    self.__len = len(materialized)
+                else:
+                    self.__data = iter(source)
+                    self.__len = data_len
+        self.__index = 0  # 当前已消费的位置（惰性迭代用）
+
+    # ===== 长度 / 索引 =====
+    def __len__(self) -> int:
+        return self.__len
+
+    def __getitem__(self, index: int) -> T:
+        # 大数据不支持随机访问：随机访问要求把数据全部物化进内存，
+        # 这与"惰性流"的核心设计冲突。要用第 N 个元素，请用 itertools.islice 流式跳过
+        raise NotImplementedError(
+            "Index access is not supported for big data, use itertools.islice instead"
+        )
+
+    # ===== 迭代协议 =====
+    def __iter__(self) -> Iterator[T]:
+        # 惰性迭代：返回 self，让 for 循环调用 __next__ 逐个取值
+        # 不预读任何数据，next 一次产出一个
+        return self
+
+    def __next__(self) -> T:
+        # 标准 Python 迭代器协议：耗尽抛 StopIteration。
+        # 这样 `for x in big` / `list(big)` 都能正常结束，
+        # 不会因为循环语义而卡死。
+        try:
+            item = next(self.__data)
+        except StopIteration:
+            raise
+        self.__index += 1
+        return item  # type: ignore[no-any-return]  # __data 持 Any，运行时为 T
+
+    # ===== 配置访问（mixin 用）=====
+    def _get_config(self) -> BigArrayConfig:
+        """返回实例的 BigArrayConfig（供算子读取阈值）。"""
+        return self.__config
+
+    # ===== 核心机制：独立迭代器 =====
+    def _fresh_iter(self) -> Iterator[T]:
+        """返回一份基于原始 source 的全新独立迭代器。
+
+        所有算子（_append_iter / _remove_iter / find / sort / ...）
+        统一通过本方法拿一份**独立**的局部迭代器，全程操作局部变量，
+        绝不碰 self.__data——避免算子之间互相污染实例状态。
+
+        self.__data 只留给 __next__ 对外 for 循环用。
+        """
+        src = self.__source
+        if isinstance(src, int):
+            # int source：生成全 0 流（int 兼容 T 由调用方语义保证，类型层无法表达）
+            return iter(0 for _ in range(src))  # type: ignore[misc]
+        return iter(src)
+
+    def cycle(self) -> Generator[T, None, None]:
+        """无限循环迭代器：数据耗尽后从头再来，永不停止。
+
+        想要"耗尽不停止"的循环语义时用这个，而不是直接 for x in big。
+        用法：
+            for x in itertools.islice(big.cycle(), 100):  # 只取 100 个
+                ...
+            for x in big.cycle():  # 真无限循环，必须自己 break
+                if cond: break
+        """
+        while True:
+            yield from self._fresh_iter()
+
+    def __contains__(self, target: object) -> bool:
+        """x in big_arr：线性查找 target 是否存在于数据中。
+
+        ⚠️ 关键设计：用 _fresh_iter() 拿**独立**迭代器查找，
+        不消费 self.__data——算子调用零副作用，可以重复调用。
+        找不到时返回 False（耗尽的是临时迭代器，不影响实例状态）。
+        """
+        return any(item == target for item in self._fresh_iter())
+
+    # ===== 反向 / 复制（与 source 类型强耦合，放核心层）=====
+    def _reverse_iter(self) -> Generator[T, None, None]:
+        """反向迭代器：从尾到头逐个产出元素。
+
+        ⚠️ 反向迭代天然要求"先看到尾才能倒着产头"，对非 int 源
+        必须物化源数据——这是反向语义的固有代价，不是设计缺陷。
+
+        按 source 类型分流：
+            - int source（全 0 测试源）：反转仍是全 0，直接生成 N 个 0
+            - list/tuple/str 等 reversible 容器：reversed(src) 视图
+            - generator source（已耗尽）：抛 TypeError
+        """
+        src = self.__source
+        if isinstance(src, int):
+            for _ in range(src):
+                yield 0  # type: ignore[misc]  # int 兼容 T 由调用方语义保证
+            return
+        try:
+            yield from reversed(src)  # type: ignore[call-overload]  # src 运行时是 Reversible 容器
+        except TypeError as e:
+            raise TypeError(
+                "无法对已耗尽的 generator source 反向迭代；请用 list/tuple 构造以支持 reverse"
+            ) from e
+
+    def _copy_iter(self) -> Generator[T, None, None]:
+        """复制迭代器：从头到尾逐个产出元素。
+
+        全程操作 _fresh_iter()，不碰 self.__data。
+        """
+        yield from self._fresh_iter()
+
+    # ===== 供子类（_api.BigArrayList）访问原始 source（copy/构造新实例） =====
+    def _get_source(self) -> int | Iterable[Any]:
+        """返回原始 source（int / list / tuple / ...）。
+
+        供 BigArrayList.copy() 等需要构造新实例的场景使用。
+        返回的是原始引用，不复制——调用方请勿修改。
+        """
+        return self.__source
+
+    # ===== 蓄水池抽样（直接放核心层，无需 mixin）=====
+    def _sample(self, k: int, seed: int | None = None) -> Generator[T, None, None]:
+        """蓄水池抽样：从总量未知的流里随机等概率抽 k 个元素。
+
+        数学保证：每个元素被选中的概率都是 k/N（N 为实际总量，无需预先知道）。
+        内存 O(k)，无需预知 N。
+
+        参数：
+            k:    要抽取的样本数（必须 >= 1，调用方校验）
+            seed: 随机种子，None 表示系统随机；传 int 可复现结果
+        """
+        yield from reservoir_sample(self._fresh_iter(), k, seed=seed)
+
+
+class BaseBigArrayList(_CoreBase[T], CRUDMixin[T], StreamMixin[T], SortMixin[T], SearchMixin[T]):
+    """大数据惰性流基类：组合核心协议 + 所有算子 mixin。
+
+    对外 API 由 _api.BigArrayList 提供（继承本类 + 参数校验）。
+    本类供"需要直接访问底层算子、不要参数校验"的场景使用。
+    """
+
+    pass
+
+
+__all__ = ["BaseBigArrayList", "BigArrayConfig", "_CoreBase", "reservoir_sample"]

bigarraylist/exceptions.py

@@ -0,0 +1,50 @@
+"""自定义异常层次。
+
+向后兼容策略：所有自定义异常都继承自 ValueError / TypeError / IndexError，
+现有 `except ValueError:` / `except TypeError:` / `except IndexError:` 调用方代码
+无需任何修改即可继续工作；想精确捕获的调用方可改用 BigArrayListError 子类。
+
+异常层次：
+
+    BigArrayListError                ← 所有自定义异常的根
+    ├── InvalidArgumentError(ValueError)   参数类型/取值不合法
+    ├── IndexOutOfRangeError(IndexError)   索引越界（start/end/index）
+    └── DataSourceError(TypeError)        source 类型不支持某操作（reverse/copy generator 源等）
+
+未来如有更细的需求，可继续在此层次下加子类。
+"""
+
+from __future__ import annotations
+
+
+class BigArrayListError(Exception):
+    """所有 BigArrayList 自定义异常的根。
+
+    继承 Exception 而非 ValueError/TypeError：本类是包内统一标识。
+    具体子类按语义分别继承 ValueError/IndexError/TypeError 以保证向后兼容。
+    """
+
+
+class InvalidArgumentError(BigArrayListError, ValueError):
+    """参数类型/取值不合法（如 max_workers < 1、num_buckets 为负数、step=0）。"""
+
+
+class IndexOutOfRangeError(BigArrayListError, IndexError):
+    """索引越界（start/end/index 超出 [0, len] 范围）。"""
+
+
+class DataSourceError(BigArrayListError, TypeError):
+    """source 类型不支持某操作。
+
+    例：
+        - generator source 已被耗尽，无法 reverse / copy
+        - 不可哈希元素走小数据 distinct 分支
+    """
+
+
+__all__ = [
+    "BigArrayListError",
+    "DataSourceError",
+    "IndexOutOfRangeError",
+    "InvalidArgumentError",
+]

bigarraylist/operators/__init__.py

@@ -0,0 +1,14 @@
+"""算子层：CRUD / 排序 / 查找 / 流式 + 链式 API。"""
+
+from .crud import CRUDMixin
+from .search import SearchMixin
+from .sort import SortMixin
+from .stream import LazyChain, StreamMixin
+
+__all__ = [
+    "CRUDMixin",
+    "LazyChain",
+    "SearchMixin",
+    "SortMixin",
+    "StreamMixin",
+]

bigarraylist/operators/crud.py

@@ -0,0 +1,89 @@
+"""CRUD 算子 mixin：惰性增 / 删 / 改 / 插。
+
+所有方法全程操作 self._fresh_iter() 返回的局部迭代器，不碰 self.__data——
+算子调用零副作用、可重复调用。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator, Iterator
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class CRUDMixin(Generic[T]):
+    """增删改插算子 mixin。
+
+    不声明 __slots__：避免与 _CoreBase 的 __slots__ 多继承冲突；
+    所有状态字段全部由 _CoreBase 持有，本 mixin 只读访问通过 self._fresh_iter()。
+
+    继承 Generic[T] 仅用于类型推导（让 T 在 mixin 内被绑定）；
+    运行时通过 cooperative multiple inheritance 与 _CoreBase 组合，
+    _fresh_iter / __len__ 等方法实际由 _CoreBase 提供。
+    """
+
+    # 类型契约：实际实现由 _CoreBase 通过 MRO 提供
+    def _fresh_iter(self) -> Iterator[T]:  # pragma: no cover - 协作契约，由 _CoreBase 实现
+        raise NotImplementedError
+
+    def _append_iter(self, *new_items: T) -> Generator[T, None, None]:
+        """惰性追加：在原流末尾接上新元素，返回新生成器。
+
+        全程操作 _fresh_iter() 返回的局部迭代器，不碰 self.__data——
+        可以重复调用，不会污染实例状态。
+        """
+        data = self._fresh_iter()
+        yield from data
+        yield from new_items
+
+    def _replace_iter(self, start: int, end: int, *new_items: T) -> Generator[T, None, None]:
+        """惰性替换：把 [start, end) 范围的元素替换成 new_items。
+
+        全程操作 _fresh_iter() 返回的局部迭代器，不碰 self.__data。
+        """
+        data = self._fresh_iter()
+        # 产出 0~start-1
+        for _ in range(start):
+            yield next(data)
+        # 丢弃 start ~ end-1
+        drop_count = end - start
+        for _ in range(drop_count):
+            next(data)
+        # 输出新内容
+        yield from new_items
+        # 输出剩余
+        yield from data
+
+    def _insert_iter(self, index: int, *new_items: T) -> Generator[T, None, None]:
+        """在指定位置插入新元素的迭代器。
+
+        全程操作 _fresh_iter() 返回的局部迭代器，不碰 self.__data。
+        """
+        data = self._fresh_iter()
+        # 产出 0~index-1
+        for _ in range(index):
+            yield next(data)
+        # 产出新增的元素
+        yield from new_items
+        # 产出剩余元素
+        yield from data
+
+    def _remove_iter(self, start: int, end: int) -> Generator[T, None, None]:
+        """惰性删除：跳过 [start, end) 范围的元素，其余照常产出。
+
+        全程操作 _fresh_iter() 返回的局部迭代器，不碰 self.__data。
+        """
+        data = self._fresh_iter()
+        # 产出 0~start-1
+        for _ in range(start):
+            yield next(data)
+        # 丢弃 start ~ end-1
+        drop_count = end - start
+        for _ in range(drop_count):
+            next(data)
+        # 产出剩余元素
+        yield from data
+
+
+__all__ = ["CRUDMixin"]

bigarraylist/operators/search.py

@@ -0,0 +1,212 @@
+"""查找算子 mixin：并行线性查找 / 二分查找 / 持久化分桶查找 / 二级索引 / 自动查找入口。
+
+核心改进（对比重构前）：
+    - _bucket_find 改为复用 algorithms.bucket.build_buckets，
+      持久化 BucketIndex 让多次查询真正复用（重构前每次重建桶）。
+    - 新增 _build_buckets() 公共方法，返回 BucketIndex 给用户跨多次 find 复用。
+    - 阈值改走 BigArrayConfig（self._get_config()）。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Generator, Iterator
+from concurrent.futures import ProcessPoolExecutor
+from typing import Any, Generic, TypeVar
+
+from ..algorithms.bucket import BucketIndex, build_buckets
+from ..algorithms.parallel import linear_find_in_chunk
+from ..config import BigArrayConfig
+from ..utils.scale import choose_chunk_size
+
+T = TypeVar("T")
+
+
+class SearchMixin(Generic[T]):
+    """查找算子 mixin。不声明 __slots__。
+
+    继承 Generic[T] 仅用于类型推导；运行时通过 cooperative multiple
+    inheritance 与 _CoreBase 组合，_fresh_iter / __len__ / _get_config
+    实际由 _CoreBase 提供（MRO 中 _CoreBase 在前，stub 被覆盖）。
+    """
+
+    # 协作契约：实际实现由 _CoreBase 通过 MRO 提供
+    def __len__(self) -> int:  # pragma: no cover - 协作契约
+        raise NotImplementedError
+
+    def _fresh_iter(self) -> Iterator[T]:  # pragma: no cover - 协作契约
+        raise NotImplementedError
+
+    def _get_config(self) -> BigArrayConfig:  # pragma: no cover - 协作契约
+        raise NotImplementedError
+
+    def _parallel_find(
+        self,
+        target: T,
+        max_workers: int | None = None,
+    ) -> Generator[tuple[int, T], None, None]:
+        """并行分块线性查找（惰性生成器）：每个进程负责一个 chunk 的线性查找。
+
+        - 数据量 < config.linear_parallel_threshold：直接线性 yield（不开进程）
+        - 数据量 >= threshold：流式物化分块 + 多进程并行，按块提交顺序 yield
+        - 惰性：不收集所有结果到 list，调用方 next 一次产出一个 (下标, 元素)
+        """
+        n = len(self)
+        cfg: BigArrayConfig = self._get_config()
+        data = self._fresh_iter()
+
+        # 小数据：进程启动开销 > 收益，直接线性 yield
+        if n < cfg.linear_parallel_threshold:
+            for i, item in enumerate(data):
+                if item == target:
+                    yield (i, item)
+            return
+
+        chunk_size = choose_chunk_size(n)
+
+        # 注意：不能用 with 块——生成器要在 with 外 yield，
+        # 而 with 退出会关池。所以手动管理生命周期：try/finally 在生成器结束时 shutdown。
+        pool = ProcessPoolExecutor(max_workers=max_workers)
+        try:
+            futures = []
+            chunk: list[T] = []
+            current_index = 0
+            for item in data:
+                chunk.append(item)
+                if len(chunk) >= chunk_size:
+                    futures.append(
+                        pool.submit(linear_find_in_chunk, (chunk, target, current_index))
+                    )
+                    current_index += len(chunk)
+                    chunk = []
+            if chunk:
+                futures.append(pool.submit(linear_find_in_chunk, (chunk, target, current_index)))
+
+            # 按块提交顺序 yield 结果（保留下标单调递增）
+            for fut in futures:
+                yield from fut.result()
+        finally:
+            pool.shutdown(wait=False)
+
+    def _bucket_find(
+        self,
+        target: T,
+        key_func: Callable[[T], Any] | None = None,
+        num_buckets: int | None = None,
+        max_workers: int | None = None,
+    ) -> Generator[tuple[int, T], None, None]:
+        """分桶查找：按 key 的哈希值把数据流式分到 N 个桶文件，
+        只扫目标桶即可定位所有命中元素，避免全量线性扫描。
+
+        重构后改进：内部走 algorithms.bucket.build_buckets 拿到 BucketIndex，
+        再调 BucketIndex.find(target)。多次查询应直接用 build_buckets 复用。
+        本方法每次调用都重建桶——保持零副作用、向后兼容。
+        """
+        n = len(self)
+        cfg: BigArrayConfig = self._get_config()
+
+        # 小数据：不分桶，直接线性扫（建桶开销不划算）
+        if n < cfg.linear_parallel_threshold:
+            kf = key_func if key_func is not None else (lambda x: x)
+            target_key = kf(target)
+            for i, item in enumerate(self._fresh_iter()):
+                if kf(item) == target_key:
+                    yield (i, item)
+            return
+
+        # 大数据：建桶 + 单桶扫（建完即查即弃；多次查询请直接用 build_buckets）
+        idx = build_buckets(
+            self._fresh_iter(),
+            n,
+            key_func=key_func,
+            num_buckets=num_buckets,
+            config=cfg,
+        )
+        try:
+            yield from idx.find(target)
+        finally:
+            idx.close()
+
+    def _build_buckets(
+        self,
+        key_func: Callable[[T], Any] | None = None,
+        num_buckets: int | None = None,
+    ) -> BucketIndex:
+        """建持久化分桶索引，返回 BucketIndex。
+
+        与 _bucket_find 的区别：
+            - _bucket_find：建桶 + 查一次 + 销毁桶，仅适合单次查
+            - _build_buckets：建桶一次返回 BucketIndex，可多次 find(target)，
+              跨多次查询真正复用建桶成本。
+
+        使用：
+            with big._build_buckets(key_func=lambda u: u.id) as idx:
+                for tgt in targets:
+                    hits = list(idx.find(tgt))
+        """
+        n = len(self)
+        cfg: BigArrayConfig = self._get_config()
+        return build_buckets(
+            self._fresh_iter(),
+            n,
+            key_func=key_func,
+            num_buckets=num_buckets,
+            config=cfg,
+        )
+
+    def _build_index(self, key_func: Callable[[T], Any] | None = None) -> dict:
+        """建二级索引：dict[key] -> list[原始下标]。
+
+        内存够用时用 dict，O(n) 时间 O(n) 内存。建好的索引可反复用：
+            - 判断 key 在不在：O(1)
+            - 拿到所有命中下标列表：O(1)
+
+        注意：惰性流不支持随机访问（__getitem__ 抛 NotImplementedError），
+        所以索引存的是下标，要拿元素仍需流式扫。索引的核心价值是
+        "建目录快速定位下标"，省去线性扫判断 key 在不在的 O(n) 开销。
+
+        约束：key_func 必须满足 a==b → key(a)==key(b)，
+        且 hash(key(a)) == hash(key(b))，否则索引会漏命中。
+
+        全程操作 _fresh_iter()，不碰 self.__data——可重复调用。
+        """
+        if key_func is None:
+            key_func = lambda x: x  # noqa: E731
+        index: dict[Any, list[int]] = {}
+        for i, item in enumerate(self._fresh_iter()):
+            k = key_func(item)
+            if k in index:
+                index[k].append(i)
+            else:
+                index[k] = [i]
+        return index
+
+    def _auto_find(
+        self,
+        target: T,
+        key_func: Callable[[T], Any] | None = None,
+        num_buckets: int | None = None,
+        max_workers: int | None = None,
+    ) -> Generator[tuple[int, T], None, None]:
+        """统一查找入口：根据数据量自动选策略。
+
+        策略：
+            - 小数据（< config.linear_parallel_threshold）：直接线性查找
+            - 大数据（>= threshold）：分桶查找（建桶 + 单桶扫）
+
+        不做 binary_search（要排序+返回排序后下标，语义不同）。
+        不缓存预处理结果（零副作用；查很多次请直接用 build_buckets）。
+        """
+        n = len(self)
+        cfg: BigArrayConfig = self._get_config()
+        if n < cfg.linear_parallel_threshold:
+            yield from self._parallel_find(target, max_workers=max_workers)
+        else:
+            yield from self._bucket_find(
+                target,
+                key_func=key_func,
+                num_buckets=num_buckets,
+                max_workers=max_workers,
+            )
+
+
+__all__ = ["SearchMixin"]