py-fastplus 0.2.1__tar.gz → 0.3.0__tar.gz

{py_fastplus-0.2.1 → py_fastplus-0.3.0}/.github/workflows/Publish.yml

@@ -187,12 +187,17 @@ jobs:
         uses: actions/attest@v4
         with:
           subject-path: 'wheels-*/*'
+      - name: Recreate latest release
+        if: ${{ steps.release-tag.outputs.tag == 'dev-latest' || steps.release-tag.outputs.tag == 'main-latest' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ steps.release-tag.outputs.tag }}
+        run: gh release delete "$RELEASE_TAG" --yes || true
       - name: Create or update GitHub Release
         uses: softprops/action-gh-release@v3
         with:
           tag_name: ${{ steps.release-tag.outputs.tag }}
-          body: FastPlus release generated by the Publish workflow.
-          generate_release_notes: false
+          generate_release_notes: true
           append_body: false
           overwrite_files: true
           files: wheels-*/*

{py_fastplus-0.2.1 → py_fastplus-0.3.0}/Cargo.lock

@@ -4,7 +4,7 @@ version = 4
 
 [[package]]
 name = "fastplus"
-version = "0.2.1"
+version = "0.3.0"
 dependencies = [
  "pest",
  "pest_derive",

{py_fastplus-0.2.1 → py_fastplus-0.3.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name    = "fastplus"
-version = "0.2.1"
+version = "0.3.0"
 edition = "2024"
 readme = "README.md"
 

py_fastplus-0.3.0/PKG-INFO

@@ -0,0 +1,286 @@
+Metadata-Version: 2.4
+Name: py-fastplus
+Version: 0.3.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+License-File: LICENSE
+Summary: Add your description here
+Author-email: AshSwing <ashswing@email.cn>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# FastPlus
+
+FastPlus 是一个基于 Rust 和 PyO3 实现的 WorldQuant Fast Expression 解析器。它把 Alpha 表达式解析为可访问的 Python 对象，并在解析已知操作符时进行参数数量、参数类型和部分操作符专属规则检查。
+
+当前实现面向 RegularAlpha，收录了 Expert 权限范围内的 108 个操作符。
+
+## 安装
+
+FastPlus 需要 Python 3.12 及以上版本。
+
+从 PyPI 安装：
+
+```bash
+pip install py-fastplus
+```
+
+如果需要从源码开发：
+
+```bash
+uv sync
+source .venv/bin/activate
+maturin develop --skip-install
+```
+
+安装后可以在 Python 中导入：
+
+```python
+import fastplus
+```
+
+## Python 用法
+
+使用 `fastplus.parse` 解析一个 Alpha 表达式：
+
+```python
+import fastplus
+
+alpha = fastplus.parse("a=ts_delay(close, 5); group_rank(a, industry)")
+
+print(alpha.fields)
+print(alpha.operators)
+```
+
+输出：
+
+```text
+{'matrix': ['close'], 'vector': [], 'group': ['industry']}
+['ts_delay', 'group_rank']
+```
+
+`Alpha` 提供以下属性：
+
+- `assignments`：赋值语句列表，每个元素包含 `variable` 和 `value`。
+- `signal`：最终信号表达式。
+- `fields`：按 `matrix`、`vector`、`group` 分类的数据字段名称。
+- `operators`：表达式中使用的操作符名称列表。
+
+解析失败会抛出 `ValueError`。例如：
+
+最终 `signal` 不能是 `Group` 或 `Vector`：
+
+```python
+fastplus.parse("bucket(rank(x), range='0, 1, 0.1')")
+```
+
+```text
+ --> 1:1
+  |
+1 | bucket(rank(x), range='0, 1, 0.1')
+  | ^--------------------------------^
+  |
+  = signal must be Matrix-compatible, but got Group
+```
+
+`bucket` 不能同时提供有效的 `range` 和 `buckets`：
+
+```python
+fastplus.parse("bucket(rank(x), range='0, 1, 0.1', buckets='0, 0.5, 1')")
+```
+
+```text
+ --> 1:1
+  |
+1 | bucket(rank(x), range='0, 1, 0.1', buckets='0, 0.5, 1')
+  | ^-----------------------------------------------------^
+  |
+  = operator `bucket` check failed: InvalidExpression("bucket requires exactly one of range and buckets to be valid")
+```
+
+`vec_*` 操作符要求 `Vector`，不能把其他返回 `Matrix` 的操作嵌进去：
+
+```python
+fastplus.parse("vec_avg(rank(x))")
+```
+
+```text
+ --> 1:1
+  |
+1 | vec_avg(rank(x))
+  | ^--------------^
+  |
+  = operator `vec_avg` check failed: InvalidArgumentType { expected: Vector, actual: Matrix }
+```
+
+异常信息会同时指出错误位置、操作符名称、错误类型、期望类型和实际类型，便于研究员和大模型定位问题并自动修复表达式。
+
+## FastPlus 语法
+
+### Alpha 和赋值
+
+一个 Alpha 由零个或多个赋值语句和一个最终信号组成：
+
+```text
+[variable = expression;] expression [;]
+```
+
+例如：
+
+```text
+adv = ts_mean(volume, 20);
+signal = rank(adv);
+signal
+```
+
+赋值左侧只能是普通变量，不能使用占位符。最后一个分号可选。
+
+### 变量、字段和占位符
+
+普通变量由字母开头，只能包含 ASCII 字母、数字和下划线：
+
+```text
+close
+industry
+my_signal_1
+```
+
+占位符必须使用完整形式：
+
+```text
+<close_field/>
+```
+
+目前不支持常数占位符，例如 `<1/>` 或 `<0.5/>`。占位符会统一作为数据字段处理，并在 `Alpha.fields` 中保留完整的 `<`、`/>` 标记。
+
+已知操作符会根据参数签名把变量和占位符分类为 `matrix`、`vector` 或 `group`。未知变量在无法确定类型时作为通配类型处理；赋值左侧定义的变量不会被计入 `fields`。
+
+### 操作符调用
+
+操作符调用格式为：
+
+```text
+operator(positional_arg, ..., keyword=value, ...)
+```
+
+位置参数必须写在关键字参数之前，关键字参数只能使用常量：
+
+```text
+add(close, volume, filter=true)
+clamp(x, lower=-1, upper=1, inverse=false, mask='mean')
+```
+
+已知操作符会检查：
+
+- 位置参数数量；
+- 位置参数类型；
+- 关键字名称和类型；
+- 必填关键字参数；
+- 部分操作符专属约束，例如 `k <= d`、`clamp` 的上下界关系，以及 `bucket` 的参数互斥和数组顺序。
+
+未知操作符会保留在表达式中，但跳过操作符检查。
+
+当前实现中的几个平台差异：
+
+- `subtract` 目前只支持两个位置参数。
+- `add`、`multiply`、`max`、`min` 等可变参数操作符至少需要两个位置参数。
+- `jump_decay` 的位置参数是 `x`、`d`，关键字参数是 `stddev`、`sensitivity`、`force`。
+- `ts_rank_gmean_amean_diff` 使用必填的 `lookback` 关键字参数。
+- 其他包含 lookback 语义的时间序列操作符通常把 lookback 作为最后一个位置参数，例如 `ts_backfill(x, d)` 和 `ts_rank(x, d)`。
+- 关键字参数只能使用常量，不能传入变量、占位符或复杂表达式。
+- 操作符至少需要一个位置参数；位置参数和关键字参数不能交错。
+
+### 表达式和运算符
+
+支持括号、前缀运算、二元运算和三元表达式：
+
+```text
+-(x + 1)
+x > 0 && y < 1
+x ? y : z
+```
+
+支持的二元运算符包括：
+
+```text
+||  &&  !=  ==  >=  <=  >  <  +  -  *  /
+```
+
+支持的前缀运算符包括：
+
+```text
+!  +  -
+```
+
+三元表达式的三个分支都必须是完整表达式。
+
+### 常量和关键字参数
+
+支持整数、浮点数、布尔值和字符串常量。数值常量会根据值归类为整数、正整数、比例、浮点数等类型；数值标量可以按平台规则广播为 `Matrix`。
+
+字符串关键字会经过统一解析，例如：
+
+```text
+driver='gaussian'
+mask='nearest_bound'
+mask='mean'
+ignore='NaN'
+```
+
+还支持范围、数组和集合形式，例如：
+
+```text
+range='0, 1, 0.1'
+buckets='0, 0.2, 0.5, 1'
+ignore='NaN 0 1'
+```
+
+### 注释和空白
+
+空格、制表符和换行会被忽略。支持以下注释：
+
+```text
+// 行注释
+# 行注释
+/* 块注释 */
+```
+
+## 当前限制和待开发功能
+
+### 操作符权限范围
+
+当前只有 Expert 权限，因此只能完整检查 Expert 范围内的操作符。未知操作符会跳过检查，以便后续扩展；欢迎提交 Pull Request 补充操作符签名和规则。
+
+### 当前不会检查的规则
+
+以下表达式按平台规则应该失败，但当前还没有检测：
+
+- 定义了但没有使用的变量；
+- 用户定义变量与数据字段重名。
+- 字段分类的交叉校验：如果同一个字段同时出现在 `matrix` 和 `vector`（或其他类别）中，说明至少有一个位置的类型推断错误，目前尚未检测。
+
+### 待开发功能
+
+- 模板展开：根据占位符自动生成具体表达式。
+- 参数遍历：遍历参数空间并生成参数组合。
+- AST 结构化输出：提供 `.format()` 方法。
+- 表达式编译：提供 `.compile()` 方法，自动合并同类项并优化因子表达式结构。
+- 补充更多权限级别的操作符和操作符专属校验。
+
+## 开发验证
+
+Rust 测试和检查：
+
+```bash
+cargo fmt -- --check
+cargo test --lib
+cargo clippy --all-targets --all-features -- -D warnings
+```
+
+Python 测试和类型检查：
+
+```bash
+uv run pytest
+uv run ty check
+```
+

py_fastplus-0.3.0/README.md

@@ -0,0 +1,274 @@
+# FastPlus
+
+FastPlus 是一个基于 Rust 和 PyO3 实现的 WorldQuant Fast Expression 解析器。它把 Alpha 表达式解析为可访问的 Python 对象，并在解析已知操作符时进行参数数量、参数类型和部分操作符专属规则检查。
+
+当前实现面向 RegularAlpha，收录了 Expert 权限范围内的 108 个操作符。
+
+## 安装
+
+FastPlus 需要 Python 3.12 及以上版本。
+
+从 PyPI 安装：
+
+```bash
+pip install py-fastplus
+```
+
+如果需要从源码开发：
+
+```bash
+uv sync
+source .venv/bin/activate
+maturin develop --skip-install
+```
+
+安装后可以在 Python 中导入：
+
+```python
+import fastplus
+```
+
+## Python 用法
+
+使用 `fastplus.parse` 解析一个 Alpha 表达式：
+
+```python
+import fastplus
+
+alpha = fastplus.parse("a=ts_delay(close, 5); group_rank(a, industry)")
+
+print(alpha.fields)
+print(alpha.operators)
+```
+
+输出：
+
+```text
+{'matrix': ['close'], 'vector': [], 'group': ['industry']}
+['ts_delay', 'group_rank']
+```
+
+`Alpha` 提供以下属性：
+
+- `assignments`：赋值语句列表，每个元素包含 `variable` 和 `value`。
+- `signal`：最终信号表达式。
+- `fields`：按 `matrix`、`vector`、`group` 分类的数据字段名称。
+- `operators`：表达式中使用的操作符名称列表。
+
+解析失败会抛出 `ValueError`。例如：
+
+最终 `signal` 不能是 `Group` 或 `Vector`：
+
+```python
+fastplus.parse("bucket(rank(x), range='0, 1, 0.1')")
+```
+
+```text
+ --> 1:1
+  |
+1 | bucket(rank(x), range='0, 1, 0.1')
+  | ^--------------------------------^
+  |
+  = signal must be Matrix-compatible, but got Group
+```
+
+`bucket` 不能同时提供有效的 `range` 和 `buckets`：
+
+```python
+fastplus.parse("bucket(rank(x), range='0, 1, 0.1', buckets='0, 0.5, 1')")
+```
+
+```text
+ --> 1:1
+  |
+1 | bucket(rank(x), range='0, 1, 0.1', buckets='0, 0.5, 1')
+  | ^-----------------------------------------------------^
+  |
+  = operator `bucket` check failed: InvalidExpression("bucket requires exactly one of range and buckets to be valid")
+```
+
+`vec_*` 操作符要求 `Vector`，不能把其他返回 `Matrix` 的操作嵌进去：
+
+```python
+fastplus.parse("vec_avg(rank(x))")
+```
+
+```text
+ --> 1:1
+  |
+1 | vec_avg(rank(x))
+  | ^--------------^
+  |
+  = operator `vec_avg` check failed: InvalidArgumentType { expected: Vector, actual: Matrix }
+```
+
+异常信息会同时指出错误位置、操作符名称、错误类型、期望类型和实际类型，便于研究员和大模型定位问题并自动修复表达式。
+
+## FastPlus 语法
+
+### Alpha 和赋值
+
+一个 Alpha 由零个或多个赋值语句和一个最终信号组成：
+
+```text
+[variable = expression;] expression [;]
+```
+
+例如：
+
+```text
+adv = ts_mean(volume, 20);
+signal = rank(adv);
+signal
+```
+
+赋值左侧只能是普通变量，不能使用占位符。最后一个分号可选。
+
+### 变量、字段和占位符
+
+普通变量由字母开头，只能包含 ASCII 字母、数字和下划线：
+
+```text
+close
+industry
+my_signal_1
+```
+
+占位符必须使用完整形式：
+
+```text
+<close_field/>
+```
+
+目前不支持常数占位符，例如 `<1/>` 或 `<0.5/>`。占位符会统一作为数据字段处理，并在 `Alpha.fields` 中保留完整的 `<`、`/>` 标记。
+
+已知操作符会根据参数签名把变量和占位符分类为 `matrix`、`vector` 或 `group`。未知变量在无法确定类型时作为通配类型处理；赋值左侧定义的变量不会被计入 `fields`。
+
+### 操作符调用
+
+操作符调用格式为：
+
+```text
+operator(positional_arg, ..., keyword=value, ...)
+```
+
+位置参数必须写在关键字参数之前，关键字参数只能使用常量：
+
+```text
+add(close, volume, filter=true)
+clamp(x, lower=-1, upper=1, inverse=false, mask='mean')
+```
+
+已知操作符会检查：
+
+- 位置参数数量；
+- 位置参数类型；
+- 关键字名称和类型；
+- 必填关键字参数；
+- 部分操作符专属约束，例如 `k <= d`、`clamp` 的上下界关系，以及 `bucket` 的参数互斥和数组顺序。
+
+未知操作符会保留在表达式中，但跳过操作符检查。
+
+当前实现中的几个平台差异：
+
+- `subtract` 目前只支持两个位置参数。
+- `add`、`multiply`、`max`、`min` 等可变参数操作符至少需要两个位置参数。
+- `jump_decay` 的位置参数是 `x`、`d`，关键字参数是 `stddev`、`sensitivity`、`force`。
+- `ts_rank_gmean_amean_diff` 使用必填的 `lookback` 关键字参数。
+- 其他包含 lookback 语义的时间序列操作符通常把 lookback 作为最后一个位置参数，例如 `ts_backfill(x, d)` 和 `ts_rank(x, d)`。
+- 关键字参数只能使用常量，不能传入变量、占位符或复杂表达式。
+- 操作符至少需要一个位置参数；位置参数和关键字参数不能交错。
+
+### 表达式和运算符
+
+支持括号、前缀运算、二元运算和三元表达式：
+
+```text
+-(x + 1)
+x > 0 && y < 1
+x ? y : z
+```
+
+支持的二元运算符包括：
+
+```text
+||  &&  !=  ==  >=  <=  >  <  +  -  *  /
+```
+
+支持的前缀运算符包括：
+
+```text
+!  +  -
+```
+
+三元表达式的三个分支都必须是完整表达式。
+
+### 常量和关键字参数
+
+支持整数、浮点数、布尔值和字符串常量。数值常量会根据值归类为整数、正整数、比例、浮点数等类型；数值标量可以按平台规则广播为 `Matrix`。
+
+字符串关键字会经过统一解析，例如：
+
+```text
+driver='gaussian'
+mask='nearest_bound'
+mask='mean'
+ignore='NaN'
+```
+
+还支持范围、数组和集合形式，例如：
+
+```text
+range='0, 1, 0.1'
+buckets='0, 0.2, 0.5, 1'
+ignore='NaN 0 1'
+```
+
+### 注释和空白
+
+空格、制表符和换行会被忽略。支持以下注释：
+
+```text
+// 行注释
+# 行注释
+/* 块注释 */
+```
+
+## 当前限制和待开发功能
+
+### 操作符权限范围
+
+当前只有 Expert 权限，因此只能完整检查 Expert 范围内的操作符。未知操作符会跳过检查，以便后续扩展；欢迎提交 Pull Request 补充操作符签名和规则。
+
+### 当前不会检查的规则
+
+以下表达式按平台规则应该失败，但当前还没有检测：
+
+- 定义了但没有使用的变量；
+- 用户定义变量与数据字段重名。
+- 字段分类的交叉校验：如果同一个字段同时出现在 `matrix` 和 `vector`（或其他类别）中，说明至少有一个位置的类型推断错误，目前尚未检测。
+
+### 待开发功能
+
+- 模板展开：根据占位符自动生成具体表达式。
+- 参数遍历：遍历参数空间并生成参数组合。
+- AST 结构化输出：提供 `.format()` 方法。
+- 表达式编译：提供 `.compile()` 方法，自动合并同类项并优化因子表达式结构。
+- 补充更多权限级别的操作符和操作符专属校验。
+
+## 开发验证
+
+Rust 测试和检查：
+
+```bash
+cargo fmt -- --check
+cargo test --lib
+cargo clippy --all-targets --all-features -- -D warnings
+```
+
+Python 测试和类型检查：
+
+```bash
+uv run pytest
+uv run ty check
+```

{py_fastplus-0.2.1 → py_fastplus-0.3.0}/python/fastplus/core.pyi

@@ -114,5 +114,7 @@ class Assignment:
 class Alpha:
     assignments: list[Assignment]
     signal: Expression
+    fields: dict[str, list[str]]
+    operators: list[str]
 
 def parse(input: str) -> Alpha: ...

{py_fastplus-0.2.1 → py_fastplus-0.3.0}/python/tests/test_all.py

@@ -73,3 +73,14 @@ def test_parse_tree_exposes_expression_and_constant_types():
 def test_python_parse_reports_operator_type_errors():
     with pytest.raises(ValueError, match="divide"):
         fastplus.parse("divide('not a matrix', 2)")
+
+
+def test_alpha_reports_typed_fields_and_operators():
+    alpha = fastplus.parse("a=ts_delay(close, 5);group_rank(a, industry)")
+
+    assert alpha.fields == {
+        "matrix": ["close"],
+        "vector": [],
+        "group": ["industry"],
+    }
+    assert alpha.operators == ["ts_delay", "group_rank"]

py_fastplus-0.3.0/src/ast.rs

@@ -0,0 +1,279 @@
+//! AST
+//! 唯一结果对象: Alpha
+//!     |-> [Assignment;]         赋值语句
+//!     |-> [Assignment;]         赋值语句
+//!     |-> [...;]                ...
+//!     |-> signal(Expression)    信号表达式
+//! Alpha 由 N 个赋值语句和 1 个信号表达式组成
+//!
+//! Assignment 赋值语句
+//!     |-> variable(String) = value(Expression);
+//!
+//! 核心结构: Expression 表达式
+//!     |-> Group(Expression) / Ternary / Binary / Unary 递归结构
+//!     |-> Variable / Placeholder                       占位结构
+//!     |-> Operation*                                   操作符*
+//!     |-> Constant*                                    常数项*
+//!
+//! 特殊规则:
+//!   - 不可以给常数赋值 ❌    -> 刚试了下又可以了(2026-07-28)
+//!   - 不可复用数据字段名     -> 非左值 Variable 都是数据字段
+//!   - 参数支持字符串/字面值  -> 自动转为字符串解析
+//!   - 支持 NaN, 不支持 Inf
+
+use std::collections::HashMap;
+use std::collections::HashSet;
+
+use crate::field::Constant;
+use crate::field::Field;
+use crate::operator::get_operator;
+
+use pest_derive::Parser;
+
+#[derive(Parser)]
+#[grammar = "fastplus.pest"]
+pub struct FastPlusParser;
+
+#[derive(Debug, Clone)]
+pub struct Alpha {
+    assignments: Vec<Assignment>,
+    signal: Expression,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct AlphaFields {
+    pub matrix: Vec<String>,
+    pub vector: Vec<String>,
+    pub group: Vec<String>,
+}
+
+impl Alpha {
+    pub fn new(assignments: Vec<Assignment>, signal: Expression) -> Self {
+        Alpha {
+            assignments,
+            signal,
+        }
+    }
+
+    pub fn signal(&self) -> &Expression {
+        &self.signal
+    }
+
+    pub fn assignments(&self) -> &[Assignment] {
+        &self.assignments
+    }
+
+    pub fn fields(&self) -> AlphaFields {
+        let defined: HashSet<_> = self
+            .assignments
+            .iter()
+            .map(|assignment| assignment.variable.clone())
+            .collect();
+        let mut fields = AlphaFields::default();
+
+        for assignment in &self.assignments {
+            collect_fields(
+                &assignment.value,
+                &Field::Matrix,
+                &defined,
+                &mut fields,
+                &mut Vec::new(),
+            );
+        }
+        collect_fields(
+            &self.signal,
+            &Field::Matrix,
+            &defined,
+            &mut fields,
+            &mut Vec::new(),
+        );
+        fields
+    }
+
+    pub fn operators(&self) -> Vec<String> {
+        let mut operators = Vec::new();
+        for assignment in &self.assignments {
+            collect_operators(&assignment.value, &mut operators);
+        }
+        collect_operators(&self.signal, &mut operators);
+        operators
+    }
+}
+
+fn collect_fields(
+    expression: &Expression,
+    expected: &Field,
+    defined: &HashSet<String>,
+    fields: &mut AlphaFields,
+    operators: &mut Vec<String>,
+) {
+    match expression {
+        Expression::Variable(name) if !defined.contains(name) => {
+            add_field(fields, expected, name.clone());
+        }
+        Expression::Variable(_) => {}
+        Expression::Placeholder(name) => add_field(fields, expected, name.clone()),
+        Expression::Group(expression) => {
+            collect_fields(expression, expected, defined, fields, operators)
+        }
+        Expression::Operation {
+            op,
+            pos_args,
+            kw_args: _,
+        } => {
+            add_operator(operators, op);
+            if let Some(operator) = get_operator(op) {
+                for (index, argument) in pos_args.iter().enumerate() {
+                    if let Some(argument_type) = if operator.nary == -1 {
+                        operator.pos_args.first()
+                    } else {
+                        operator.pos_args.get(index)
+                    } {
+                        collect_fields(argument, argument_type, defined, fields, operators);
+                    } else {
+                        collect_fields(argument, &Field::Matrix, defined, fields, operators);
+                    }
+                }
+            } else {
+                for argument in pos_args {
+                    collect_fields(argument, &Field::Matrix, defined, fields, operators);
+                }
+            }
+        }
+        Expression::Ternary {
+            cond,
+            then_branch,
+            else_branch,
+        } => {
+            collect_fields(cond, &Field::Matrix, defined, fields, operators);
+            collect_fields(then_branch, &Field::Matrix, defined, fields, operators);
+            collect_fields(else_branch, &Field::Matrix, defined, fields, operators);
+        }
+        Expression::Binary { left, right, .. } => {
+            collect_fields(left, &Field::Matrix, defined, fields, operators);
+            collect_fields(right, &Field::Matrix, defined, fields, operators);
+        }
+        Expression::Unary { expr, .. } => {
+            collect_fields(expr, &Field::Matrix, defined, fields, operators)
+        }
+        Expression::Constant(_) => {}
+    }
+}
+
+fn collect_operators(expression: &Expression, operators: &mut Vec<String>) {
+    match expression {
+        Expression::Operation { op, pos_args, .. } => {
+            add_operator(operators, op);
+            for argument in pos_args {
+                collect_operators(argument, operators);
+            }
+        }
+        Expression::Group(expression) => collect_operators(expression, operators),
+        Expression::Ternary {
+            cond,
+            then_branch,
+            else_branch,
+        } => {
+            collect_operators(cond, operators);
+            collect_operators(then_branch, operators);
+            collect_operators(else_branch, operators);
+        }
+        Expression::Binary { left, right, .. } => {
+            collect_operators(left, operators);
+            collect_operators(right, operators);
+        }
+        Expression::Unary { expr, .. } => collect_operators(expr, operators),
+        Expression::Constant(_) | Expression::Placeholder(_) | Expression::Variable(_) => {}
+    }
+}
+
+fn add_field(fields: &mut AlphaFields, expected: &Field, name: String) {
+    let target = match expected {
+        Field::Vector => &mut fields.vector,
+        Field::Group => &mut fields.group,
+        _ => &mut fields.matrix,
+    };
+    if !target.contains(&name) {
+        target.push(name);
+    }
+}
+
+fn add_operator(operators: &mut Vec<String>, name: &str) {
+    if !operators.iter().any(|operator| operator == name) {
+        operators.push(name.to_string());
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct Assignment {
+    variable: String,
+    value: Expression,
+}
+
+impl Assignment {
+    pub fn new(variable: String, value: Expression) -> Self {
+        Assignment { variable, value }
+    }
+
+    pub fn variable(&self) -> &str {
+        &self.variable
+    }
+
+    pub fn value(&self) -> &Expression {
+        &self.value
+    }
+}
+
+#[derive(Debug, Clone)]
+pub enum BinaryOp {
+    NotEqual,     // !=
+    Equal,        // ==
+    GreaterEqual, // >=
+    LessEqual,    // <=
+    Greater,      // >
+    Less,         // <
+    Add,          // +
+    Subtract,     // -
+    Multiply,     // *
+    Divide,       // /
+    Or,           // ||
+    And,          // &&
+}
+
+#[derive(Debug, Clone)]
+pub enum UnaryOp {
+    Positive, // +
+    Negative, // -
+    Not,      // !
+}
+
+#[derive(Debug, Clone)]
+pub enum Expression {
+    Ternary {
+        // cond ? true_val : false_val
+        cond: Box<Expression>,
+        then_branch: Box<Expression>,
+        else_branch: Box<Expression>,
+    },
+    Binary {
+        // left op right
+        left: Box<Expression>,
+        op: BinaryOp,
+        right: Box<Expression>,
+    },
+    Unary {
+        // op expr
+        op: UnaryOp,
+        expr: Box<Expression>,
+    },
+    Operation {
+        // op(args)
+        op: String,
+        pos_args: Vec<Expression>,
+        kw_args: HashMap<String, Constant>,
+    },
+    Constant(Constant),
+    Placeholder(String),
+    Variable(String),
+    Group(Box<Expression>),
+}

{py_fastplus-0.2.1 → py_fastplus-0.3.0}/src/operator.rs

@@ -1220,7 +1220,7 @@ define_operator_registry! {
         {
             "lower" => (Number, None),
             "upper" => (Number, None),
-            "inverse" => (Boolean, None),
+            "inverse" => (Boolean, Some(Constant::Boolean(false))),
             "mask" => (Mask, Some(Constant::NaN)),
         },
         1,

{py_fastplus-0.2.1 → py_fastplus-0.3.0}/src/parser.rs

@@ -109,15 +109,25 @@ fn build_alpha(pair: Pair<Rule>) -> Result<Alpha, PestError<Rule>> {
                     }
                 }
             }
-            Ok(Alpha::new(
-                assignments,
-                signal.ok_or(PestError::new_from_span(
+            let signal = signal.ok_or(PestError::new_from_span(
+                CustomError {
+                    message: "因子只有赋值语句, 缺少信号表达式".to_string(),
+                },
+                span,
+            ))?;
+            if let Some(signal_type) = infer_field(&signal)
+                && !Field::Matrix.fit(&signal_type)
+            {
+                return Err(PestError::new_from_span(
                     CustomError {
-                        message: "因子只有赋值语句, 缺少信号表达式".to_string(),
+                        message: format!(
+                            "signal must be Matrix-compatible, but got {signal_type:?}"
+                        ),
                     },
                     span,
-                ))?,
-            ))
+                ));
+            }
+            Ok(Alpha::new(assignments, signal))
         }
         other => Err(PestError::new_from_span(
             CustomError {
@@ -436,6 +446,15 @@ mod tests {
         }
     }
 
+    #[test]
+    fn signal_must_be_matrix_compatible() {
+        assert!(parse("group_rank(x, industry)").is_ok());
+        assert!(parse("vec_avg(<prices/>)").is_ok());
+        assert!(parse("42").is_ok());
+        assert!(parse("bucket(rank(x), range='0, 1, 0.1')").is_err());
+        assert!(parse("bucket(rank(x), buckets='0, 1')").is_err());
+    }
+
     #[test]
     fn parse_failure() {
         let inputs = [
@@ -464,6 +483,21 @@ mod tests {
         assert!(parse("divide(x)").is_err());
     }
 
+    #[test]
+    fn collects_typed_fields_and_operator_names() {
+        let alpha = parse("a=ts_delay(close, 5);group_rank(a, industry)").unwrap();
+        let fields = alpha.fields();
+        assert_eq!(fields.matrix, vec!["close"]);
+        assert_eq!(fields.group, vec!["industry"]);
+        assert!(fields.vector.is_empty());
+        assert_eq!(alpha.operators(), vec!["ts_delay", "group_rank"]);
+
+        let alpha = parse("vec_avg(<prices/>)").unwrap();
+        let fields = alpha.fields();
+        assert_eq!(fields.vector, vec!["<prices/>"]);
+        assert!(fields.matrix.is_empty());
+    }
+
     #[test]
     fn reports_missing_closing_parenthesis() {
         let error = parse("multiply(rank(abs(zscore(<score/>)))").unwrap_err();

{py_fastplus-0.2.1 → py_fastplus-0.3.0}/src/python.rs

@@ -275,7 +275,16 @@ py_getters!(
             },
             signal: PyResult<Py<PyExpression>>, |self, py| {
                 build_pyexpression(py, self.0.signal().clone())
-            }
+            },
+            fields: PyResult<Py<PyDict>>, |self, py| {
+                let fields = self.0.fields();
+                let dict = PyDict::new(py);
+                dict.set_item("matrix", fields.matrix)?;
+                dict.set_item("vector", fields.vector)?;
+                dict.set_item("group", fields.group)?;
+                Ok(dict.unbind())
+            },
+            operators: Vec<String>, |self, _py| { self.0.operators() },
         }
     ),
     (

py_fastplus-0.2.1/PKG-INFO

@@ -1,32 +0,0 @@
-Metadata-Version: 2.4
-Name: py-fastplus
-Version: 0.2.1
-Classifier: Programming Language :: Rust
-Classifier: Programming Language :: Python :: Implementation :: CPython
-License-File: LICENSE
-Summary: Add your description here
-Author-email: AshSwing <ashswing@email.cn>
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
-
-# FastPlus - Alpha Expression Language, based on WorldQuant's Fast Expression
-
-基于 WorldQuant Fast Expression 开发的因子表达式语法解析器.
-
-## 平台规则
-
-- 关键字参数全部都可以使用字符串类型
-- 数值标量会自动广播, 可以视作 MATRIX
-
-## 当前操作符支持范围
-
-当前实现面向 RegularAlpha，仅收录 RegularAlpha 可用的 108 个操作符。原始操作符资料中属于 SuperAlpha 的操作符暂不支持，包括 Combo、Reduce、Special 等类别中的专用操作符。
-
-当前与平台行为保持一致的限制：
-
-- `subtract` 目前只支持 `nary = 2`，即两个位置参数；平台的无限参数版本尚未实现。
-- `add`、`multiply`、`max`、`min` 等 `nary = -1` 操作符只在签名中声明一个可变参数类型，实际使用时至少需要两个位置参数，由 op-check 负责校验。
-- `jump_decay` 的位置参数为 `x` 和 `d`，关键字参数为 `stddev=false`、`sensitivity=0.5`、`force=0.1`。
-- `ts_rank_gmean_amean_diff` 要求使用 `lookback` 关键字参数，以保持表达式语法的完整性；虽然平台允许将 `d` 作为位置参数传入，FastPlus 当前不采用这种写法。
-- 除 `ts_rank_gmean_amean_diff` 外，包含 lookback 语义的时间序列操作符将 lookback 作为最后一个位置参数，例如 `ts_backfill(x, d)`、`ts_rank(x, d)`。
-

py_fastplus-0.2.1/README.md

@@ -1,20 +0,0 @@
-# FastPlus - Alpha Expression Language, based on WorldQuant's Fast Expression
-
-基于 WorldQuant Fast Expression 开发的因子表达式语法解析器.
-
-## 平台规则
-
-- 关键字参数全部都可以使用字符串类型
-- 数值标量会自动广播, 可以视作 MATRIX
-
-## 当前操作符支持范围
-
-当前实现面向 RegularAlpha，仅收录 RegularAlpha 可用的 108 个操作符。原始操作符资料中属于 SuperAlpha 的操作符暂不支持，包括 Combo、Reduce、Special 等类别中的专用操作符。
-
-当前与平台行为保持一致的限制：
-
-- `subtract` 目前只支持 `nary = 2`，即两个位置参数；平台的无限参数版本尚未实现。
-- `add`、`multiply`、`max`、`min` 等 `nary = -1` 操作符只在签名中声明一个可变参数类型，实际使用时至少需要两个位置参数，由 op-check 负责校验。
-- `jump_decay` 的位置参数为 `x` 和 `d`，关键字参数为 `stddev=false`、`sensitivity=0.5`、`force=0.1`。
-- `ts_rank_gmean_amean_diff` 要求使用 `lookback` 关键字参数，以保持表达式语法的完整性；虽然平台允许将 `d` 作为位置参数传入，FastPlus 当前不采用这种写法。
-- 除 `ts_rank_gmean_amean_diff` 外，包含 lookback 语义的时间序列操作符将 lookback 作为最后一个位置参数，例如 `ts_backfill(x, d)`、`ts_rank(x, d)`。

py_fastplus-0.2.1/src/ast.rs

@@ -1,129 +0,0 @@
-//! AST
-//! 唯一结果对象: Alpha
-//!     |-> [Assignment;]         赋值语句
-//!     |-> [Assignment;]         赋值语句
-//!     |-> [...;]                ...
-//!     |-> signal(Expression)    信号表达式
-//! Alpha 由 N 个赋值语句和 1 个信号表达式组成
-//!
-//! Assignment 赋值语句
-//!     |-> variable(String) = value(Expression);
-//!
-//! 核心结构: Expression 表达式
-//!     |-> Group(Expression) / Ternary / Binary / Unary 递归结构
-//!     |-> Variable / Placeholder                       占位结构
-//!     |-> Operation*                                   操作符*
-//!     |-> Constant*                                    常数项*
-//!
-//! 特殊规则:
-//!   - 不可以给常数赋值 ❌    -> 刚试了下又可以了(2026-07-28)
-//!   - 不可复用数据字段名     -> 非左值 Variable 都是数据字段
-//!   - 参数支持字符串/字面值  -> 自动转为字符串解析
-//!   - 支持 NaN, 不支持 Inf
-
-use std::collections::HashMap;
-
-use crate::field::Constant;
-
-use pest_derive::Parser;
-
-#[derive(Parser)]
-#[grammar = "fastplus.pest"]
-pub struct FastPlusParser;
-
-#[derive(Debug, Clone)]
-pub struct Alpha {
-    assignments: Vec<Assignment>,
-    signal: Expression,
-}
-
-impl Alpha {
-    pub fn new(assignments: Vec<Assignment>, signal: Expression) -> Self {
-        Alpha {
-            assignments,
-            signal,
-        }
-    }
-
-    pub fn signal(&self) -> &Expression {
-        &self.signal
-    }
-
-    pub fn assignments(&self) -> &[Assignment] {
-        &self.assignments
-    }
-}
-
-#[derive(Debug, Clone)]
-pub struct Assignment {
-    variable: String,
-    value: Expression,
-}
-
-impl Assignment {
-    pub fn new(variable: String, value: Expression) -> Self {
-        Assignment { variable, value }
-    }
-
-    pub fn variable(&self) -> &str {
-        &self.variable
-    }
-
-    pub fn value(&self) -> &Expression {
-        &self.value
-    }
-}
-
-#[derive(Debug, Clone)]
-pub enum BinaryOp {
-    NotEqual,     // !=
-    Equal,        // ==
-    GreaterEqual, // >=
-    LessEqual,    // <=
-    Greater,      // >
-    Less,         // <
-    Add,          // +
-    Subtract,     // -
-    Multiply,     // *
-    Divide,       // /
-    Or,           // ||
-    And,          // &&
-}
-
-#[derive(Debug, Clone)]
-pub enum UnaryOp {
-    Positive, // +
-    Negative, // -
-    Not,      // !
-}
-
-#[derive(Debug, Clone)]
-pub enum Expression {
-    Ternary {
-        // cond ? true_val : false_val
-        cond: Box<Expression>,
-        then_branch: Box<Expression>,
-        else_branch: Box<Expression>,
-    },
-    Binary {
-        // left op right
-        left: Box<Expression>,
-        op: BinaryOp,
-        right: Box<Expression>,
-    },
-    Unary {
-        // op expr
-        op: UnaryOp,
-        expr: Box<Expression>,
-    },
-    Operation {
-        // op(args)
-        op: String,
-        pos_args: Vec<Expression>,
-        kw_args: HashMap<String, Constant>,
-    },
-    Constant(Constant),
-    Placeholder(String),
-    Variable(String),
-    Group(Box<Expression>),
-}