polars-fluxbar 0.2.0

Polars plugin expressions and stream processors for flux-controlled dynamic windows.

polars-fluxbar

polars-fluxbar 是一个面向 Polars 的 Python/Rust 扩展，提供由“通量”、 局部极值数量或非零条件值数量控制的动态窗口统计能力，同时包含可在 Python 中逐行调用的流式处理器。

功能特性

• dynamic_window_stat / dynamic_window_stat_pipe：按累计条件值控制窗口长度。
• extrema_window_stat / extrema_window_stat_pipe：按局部极值数量控制窗口长度。
• nonzero_window_stat / nonzero_window_stat_pipe：按 cond != 0 的数量控制窗口长度，零值行保留在窗口内参与目标值统计。
• dynamic_window / extrema_window / nonzero_window 及对应 *_pipe：只返回目标窗口 list 列。
• *_window_stat_pipe 支持多目标列选择器，如 pl.col(["close", "open"])，多目标输出按 {prefix}{target}_{stat} 命名。
• DynamicWindowFilter / ExtremaWindowFilter / NonZeroWindowFilter：适合流式、逐 tick 或 REPL 调试的 Python 调用接口。
• Stat：统一描述 avg、sum、max、min、quantile、rank、argmax、argmin 等统计项。
• distribution_sample：按行生成确定性的分布采样结果，支持静态参数和来自列的参数。

安装

开发阶段建议先构建本地扩展：

uv sync --group dev
uv run maturin develop --release

完成构建后即可在当前虚拟环境中导入：

import polars as pl
from polars_fluxbar import Stat
from polars_fluxbar.expr import dynamic_window_stat_pipe

df = pl.DataFrame(
    {
        "volume": [1.0, 2.0, 1.0, 3.0],
        "close": [10.0, 11.0, 9.5, 12.0],
        "open": [9.8, 10.2, 10.7, 10.0],
    }
)

out = (
    df.lazy()
    .pipe(
        dynamic_window_stat_pipe,
        period=3.0,
        stats=[Stat.avg(), Stat.max(), "count"],
        cond_col="volume",
        target_col=pl.col(["close", "open"]),
        prefix="dyn_",
    )
    .collect()
)

print(out)

单目标调用保持旧命名，如 dyn_avg；多目标调用会生成 dyn_close_avg、 dyn_open_avg 等列。若只需要窗口内目标列表，可使用 dynamic_window_pipe、 extrema_window_pipe 或 nonzero_window_pipe。

更多可直接运行的示例见 examples/demo_fluxbar.py。

开发

常用检查命令：

uv run maturin develop --release
uv run pytest tests
cargo clippy --all-targets --all-features

构建发布产物：

uv run maturin build --release --sdist --compatibility pypi

发布脚本

仓库提供 scripts/gitee_release.py，用于构建/发布 PyPI 包，并将产物镜像到 Gitee Release。 发布前需要配置 .env 或环境变量，至少包含：

• PYPI_API_TOKEN
• GITEE_TOKEN

脚本只要求这两个变量存在，可以通过 .env 或执行前指定。子进程仍会继承完整环境， 以便 MSVC、Rust、uv 等构建工具正常工作。项目版本、Gitee 仓库地址、tag、release 名称和目标提交会从 pyproject.toml、Cargo.toml 与 git remote 中自动推导。

许可

本项目使用 MIT License，详见 LICENSE。