Metadata-Version: 2.4
Name: polars-fluxbar
Version: 0.1.3
Requires-Dist: polars>=1.42,<2
License-File: LICENSE
Summary: Polars plugin expressions and stream processors for flux-controlled dynamic windows.
Requires-Python: >=3.13, <3.14
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# polars-fluxbar
[![PyPI](https://img.shields.io/pypi/v/polars-fluxbar)](https://pypi.org/project/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`：按行生成确定性的分布采样结果，支持静态参数和来自列的参数。

## 安装

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

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

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

```python
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`。

## 开发

常用检查命令：

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

构建发布产物：

```powershell
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`。

