vools - Python 函数式编程工具集

📚 完整文档: https://victop-cw.github.io/vools/

一个强大的 Python 函数式编程工具集，提供装饰器、函数式编程工具、数据处理工具、响应式编程等。

特性

装饰器: memorize、once、lazy、retry、curry、overload 等
函数式编程: Seq、Ops、管道操作、占位符、箭头函数
数据处理: 链式序列操作、列表/文本增强工具
响应式编程: Observable、Subject、丰富的操作符
任务调度: TaskQueue、WorkerPool、DAG 调度器
序列化: 支持 JSON、MsgPack、Pickle 等多种格式
编码/加密: Base64、URL 编码、哈希函数
多语言桥接: 支持 27+ 种编程语言（Lua、Rust、Go、Java、Kotlin、Swift、Dart、MoonBit 等），统一装饰器接口
编译器自动发现: 自动探测本机和 WSL 环境中的编译器，支持注册表搜索、常见安装路径、通配符路径展开
跨语言操作符: Scala / Kotlin / Nim 隐式双元操作符，支持函数组合与数据管道处理

安装

pip install vools

或从源码安装：

git clone https://github.com/vicTop-cw/vools.git
cd vools
pip install .

PySpark / PostgreSQL 集成（vools-pyk）

需要 Spark / Hive / PostgreSQL 相关能力时，安装 vools-pyk（独立分发包，以 vools.pyk 命名空间合并）：

pip install "vools[pyk]"     # 推荐
# 等价：pip install vools-pyk

文档见 pyk/README.md 与 pyk/docs/。

环境要求

Python 3.6+

依赖

attrs >= 22.1 (Python < 3.7 时需要，用于 dataclass 兼容)
contextvars (Python < 3.7 时需要)

快速开始

装饰器

from vools import memorize, once, retry, overload

# 缓存装饰器
@memorize(duration=60)
def expensive_function(x):
    return x ** 2

# 只执行一次
@once
def initialize():
    return 42

# 重试装饰器
@retry(times=3, delay=1)
def risky_operation():
    pass

# 函数重载
@overload
def process(x: int) -> int:
    return x * 2

@process.register
def process(x: str) -> str:
    return x.upper()

函数式编程

from vools import Seq, Ops, _, g, iif, pipe

# Seq 链式操作
result = Seq(range(10)).filter(lambda x: x % 2 == 0).map(lambda x: x * 2).collect()
# [0, 4, 8, 12, 16]

# Ops 管道操作
result = range(10) | Ops.filter(lambda x: x > 3) | Ops.map(lambda x: x * 2) | Ops.sum()
# 84

# 占位符
f = _ + 1
print(f(2))  # 3

# 箭头函数
f = g("x, y => x + y")
print(f(3, 4))  # 7

# 条件表达式
result = iif(True, "yes", "no")  # "yes"

柯里化

from vools import curry, stuff

@curry
def add(a, b, c):
    return a + b + c

print(add(1)(2)(3))  # 6

@stuff
def multiply(a, b):
    return a * b

result = multiply(2)(3)()
print(result)  # 6

响应式编程

from vools import Observable

# 创建 Observable
obs = Observable.from_iterable([1, 2, 3, 4, 5])

# 链式操作符
result = []
obs.pipe(
    Ops.filter(lambda x: x % 2 == 0),
    Ops.map(lambda x: x * 2),
    Ops.take(2)
).subscribe(lambda x: result.append(x))

print(result)  # [4, 8]

编译器自动发现（独立包 vools-bridges）

需要先安装：pip install vools-bridges

自动探测本机和 WSL 环境中所有已安装的编译器，无需手动配置 PATH。

from vools_bridges import discover_all, get_discovery_report, configure_from_discovery

# 一键发现所有编译器（本机 + WSL）
result = discover_all(include_wsl=True)

# 查看格式化报告
print(get_discovery_report())

# 自动配置管理器
configure_from_discovery(include_wsl=True)

# 检查特定语言是否可用
from vools_bridges import get_helper
nim_helper = get_helper('nim')
if nim_helper.is_available():
    print(f"Nim 编译器路径: {nim_helper.get_compiler_path()}")

跨语言隐式操作符（Scala / Kotlin / Nim）

Scala

import com.example.operators.Operators._

def genA(): String = "Hello"
def genB(s: String): String = s"$s, World!"

val merged = genA _ #> genB _
merged() // "Hello, World!"

val doubled = List(1, 2, 3) |>> (_ * 2)
// List(2, 4, 6)

Kotlin

import com.example.operators.Operators._

fun genA(): String = "Hello"
fun genB(s: String): String = "$s, World!"

val merged = genA `#gt` genB
println(merged()) // "Hello, World!"

val doubled = listOf(1, 2, 3).pipeMap { it * 2 }
// [2, 4, 6]

Nim

import operators

proc genA(): string = "Hello"
proc genB(s: string): string = s & ", World!"

let merged = compose01(genA, genB)
echo merged() # "Hello, World!"

let doubled = pipeMap(@[1, 2, 3], proc(x: int): int = x * 2)
echo doubled # @[2, 4, 6]

项目结构

vools/
├── api/             # CLI 命令行接口
├── actus/           # Actus 动作引擎核心（执行器/工作流/注册表/安全）
├── concurrent/      # 并发工具集（跨语言桥接委托/队列/线程）
├── data/            # 增强数据类型（VList/VText/VDate/Table/Qax）
├── decorators/      # 装饰器（memorize/once/retry/curry/overload/flex_pos）
├── functional/      # 函数式编程（Seq/Ops/Box/iif/pipe/placeholder）
├── md/              # Markdown 处理（解析/生成/HTML/模板/预览）
├── oop/             # 面向对象工具（extend/calltype/method_extend）
├── reactive/        # 响应式编程（Observable/Subject）
├── serialize/       # 序列化（codec/json/msgpack/pickle）
├── sql/             # SQL 引擎（SQLite/PostgreSQL/Spark/方言/构建器）
├── sys/             # 系统命令（cmd/dll/compile/run/env/fire）
├── task/            # 任务调度（队列/工作池/线程池/DAG）
├── utils/           # 工具函数（cache/tools/funcs）
├── config.py        # 全局配置
└──                  # bridges/ 已拆分为独立分发包 vools-bridges

bridge/ 子包已拆分为独立分发包 vools-bridges（pip install vools-bridges），通过 pip install vools[bridges] 安装后使用 import vools_bridges。

详细文档

装饰器

装饰器	说明
`memorize(duration=N)`	时间缓存
`once()`	单次执行
`lazy()`	延迟执行
`repeat(cnt, delay)`	重复执行
`retry(times, delay)`	失败重试
`curry()`	柯里化
`overload()`	函数重载
`stuff()`	分步柯里化

函数式工具

工具	说明
`Seq(iterable)`	链式序列操作
`Ops`	管道操作符
`P(func)`	管道函数包装
`_`, `_1`, `_2`, `_3`	占位符
`g("x, y => ...")`	箭头函数
`iif(cond, t, f)`	条件表达式
`Box(obj)`	对象包装器

数据类型

类型	说明
`VList(list)`	增强列表
`VText(str)`	增强文本
`VDate`	日期处理

响应式

类型	说明
`Observable`	可观察对象
`Subject`	主题
`BehaviorSubject`	行为主题
`ReplaySubject`	回放主题

详细文档

性能对比

vools 通过 vools-bridges 独立包桥接 Nim/Rust/Go 等编译型语言，为高频核心函数提供可选的高性能实现。以下是典型硬件上的基准测试结果（实际数据因硬件而异）：

模块	函数	纯 Python	桥接加速	提升倍数
serialize.codec	pickle_encode	~120 us	~18 us	6-8x
serialize.codec	pickle_decode	~100 us	~15 us	6-7x
security.hash	sha256_hex	~15 us	~3 us	5x
security.hash	md5_hex	~12 us	~2 us	6x
security.hash	sha1_hex	~10 us	~2 us	5x
security.hash	sha512_hex	~18 us	~4 us	4.5x
data.seq	base64_encode	~8 us	~2 us	4x
data.seq	base64_decode	~7 us	~2 us	3.5x
serialize	json_encode	~50 us	~15 us	3x
serialize	json_decode	~45 us	~12 us	4x
data.seq	zlib_compress	~500 us	~100 us	5x
data.seq	zlib_decompress	~200 us	~50 us	4x
cache.sigcache	hash_signature	~50 us	~8 us	6x

注意：

桥接库为可选增强，未安装时自动使用纯 Python 实现
测试数据为 1KB 左右的小数据，大数据量提升更显著
详细基准测试方法请参见基准测试文档

更新日志

详细的版本更新记录请查看 CHANGELOG.md。

贡献

欢迎提交 Issue 和 Pull Request！

Fork 项目
创建功能分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
打开 Pull Request

许可证

Apache License 2.0 - 详见 LICENSE 文件

联系方式

Metadata

Release files for vools 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vools 0.8.0
File	Size	Uploaded
vools-0.8.0.tar.gz	2.4 MB	Oct 17, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for vools 0.8.0
File	Interpreter	ABI	Platform	Reset
vools-0.8.0-py3-none-any.whl 2.4 MB Oct 17, 2026	Python 3	none	any	Details

Total release size: 4.7 MB

Release files / vools-0.8.0.tar.gz

Download URL	vools-0.8.0.tar.gz
Size	2.4 MB
Tags	Source
SHA-256 checksum How to use checksums	`f3ba132ad5e35620fa3ad03577d02189ec415e6b0df77a2812ef9c95248952ed`
BLAKE2b-256 checksum How to use checksums	`be5f32908c2935e624c66bc37a97afad610b34f01a59d226c07f431652e094ad`
Upload date	Oct 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.8`

Release files / vools-0.8.0-py3-none-any.whl

Download URL	vools-0.8.0-py3-none-any.whl
Size	2.4 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`097dc9705eb644e7f0cfd0e7c519b64b1c63d72c7f24f1dc960043bf1f8a1c5b`
BLAKE2b-256 checksum How to use checksums	`5030563e5c6b8f3a5627ab36570e6cc0deb585643f95733a3a23acedf38243e5`
Upload date	Oct 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.8`