pyruts 0.1.0

面向 Rust 工程实践的 proc_macro 工具集: Builder derive, c_wrap! FFI 包装, ensure!/bail!/throw! 错误宏, dict!/btree_dict! 容器字面量
Documentation

pyruts

CI crates.io License MSRV docs.rs

一个面向 Rust 工程实践的 proc_macro 工具集

简介

pyruts 是一个 Rust proc_macro 工具集,一站式提供构建器派生、FFI 安全包装、错误传播与字典字面量等常用模式的宏实现。所有代码在编译期展开,零运行时开销——proc_macro 本身不引入任何运行时依赖。

API 设计严格对齐 derive_builder、anyhow、maplit 等世界一流库,迁移成本极低;FFI 包装宏 c_wrap! 将 unsafe 边界收敛到一处,生成的代码经 miri 验证内存安全;测试覆盖每个宏的所有属性组合,CI 同时跑 test + clippy + miri + fmt 四道关。

  • 零运行时开销:proc_macro 在编译期展开,运行时只见生成代码
  • API 对齐主流生态:Builder 对标 derive_builder,ensure!/bail!/throw! 对标 anyhow,dict!/btree_dict! 对标 maplit
  • unsafe 隔离:c_wrap! 自动生成 safe_<name> 包装,把 FFI 风险面收敛到生成代码一处
  • 完整测试:每个宏配独立测试文件,覆盖必填/可选/默认/泛型/校验等所有路径

30 秒上手

写给 Python 用户的极简速查:三个示例覆盖构造、字典与错误处理,每段附 Python 等价代码。

1. 构造结构体

use pyruts::Builder;

#[derive(Builder)]
struct Config {
    name: String,
    age: u32,
}

// Python: Config(name="alice", age=30)
// 推荐 (make! 宏, 即将支持):
//   let c = make!(Config { name: "alice", age: 30 });
// 等价 (builder, 当前可用):
let c = Config::builder()
    .with_name("alice")
    .with_age(30)
    .build()
    .unwrap();

2. 创建字典

use pyruts::dict;
use std::collections::HashMap;

// Python: {"a": 1, "b": 2}
let m: HashMap<String, i32> = dict! {
    "a": 1,
    "b": 2,
};

3. 错误处理

use pyruts::{ensure, bail};

fn check(x: i32) -> Result<i32, String> {
    // Python: assert x > 0, "x must be positive"
    ensure!(x > 0, "x must be positive, got {}", x);
    // Python: if x > 100: raise ValueError("too large")
    if x > 100 {
        bail!("too large: {}", x);
    }
    Ok(x)
}

安装

[dependencies]
pyruts = "0.1"

特性总览

宏 类型 用途 对标库
Builder derive 为结构体生成链式构造器 derive_builder
c_wrap! function-like 包装 extern "C" 块,生成 safe_<name> 安全函数 (原创,无直接对标)
ensure! function-like 条件断言,失败时立即返回错误 anyhow::ensure!
bail! function-like 立即返回格式化错误 anyhow::bail!
throw! function-like bail! 语义别名 anyhow::bail!
dict! function-like 字面量构造 HashMap(with_capacity 预分配) maplit::hashmap!
btree_dict! function-like 字面量构造 BTreeMap maplit::btreemap!
set! function-like 字面量构造 HashSet(with_capacity 预分配) maplit::hashset!
btree_set! function-like 字面量构造 BTreeSet maplit::btreeset!
make! function-like 一行构造结构体 (Python Type(...) 风格) -

Builder 宏

#[derive(Builder)] 为命名字段结构体生成 XxxBuilder 链式构造器,支持泛型、where 子句、生命周期。

字段级属性

属性 含义 示例
#[builder(default)] 未设置时用 Default::default() #[builder(default)] count: u32
#[builder(default = "expr")] 未设置时用字符串解析的表达式 #[builder(default = "42u32")] count: u32
#[builder(each = "name")] Vec<T> 字段,每次调用 name(v) 追加元素 #[builder(each = "item")] items: Vec<String>
#[builder(setter = "name")] 自定义 setter 方法名 #[builder(setter = "age")] age: u32
#[builder(setter(into))] 显式声明 setter 接受 impl Into<T>(语法糖,默认即此行为) #[builder(setter(into))] name: String
#[builder(setter(strip_option))] Option<T> 字段仅生成接受 T 的 setter,不再生成 with_xxx_option #[builder(setter(strip_option))] nick: Option<String>
#[builder(skip)] 跳过字段,不生成 setter,build 时用 Default #[builder(skip)] created_at: u64

结构体级属性

属性 含义 示例
#[builder(validate = "fn")] build 完成后调用 fn(&Self) -> Result<(), String> 进行业务校验 #[builder(validate = "check_range")]
#[builder(field_defaults(...))] 为所有字段设置默认配置,单字段可覆盖;支持 default/default = "expr"/skip/skip = bool/setter(into)/setter(strip_option) 子选项 #[builder(field_defaults(default = "0u32", skip = false))]
#[builder(builder_type(derive = "..."))] 给生成的 XxxBuilder 附加 #[derive(...)] 属性,逗号分隔多项 #[builder(builder_type(derive = "Clone, Debug"))]
#[builder(setter(strip_option))] 应用到所有 Option<T> 字段(同字段级语义,可由字段级 setter(strip_option = false) 覆盖) #[builder(setter(strip_option))]
#[builder(setter(prefix = "..."))] 控制 setter 方法名前缀(默认 "with_",设 "" 则 setter 名 = 字段名,更贴近 Python 关键字参数风格) #[builder(setter(prefix = ""))]

泛型支持

  • 自动透传泛型参数与 where 子句到 XxxBuilder<T, ...>
  • 多泛型参数、生命周期、T: Clone + Default 等约束均支持
  • validate 函数需手动泛型化并与 struct 约束对齐

生成的 API

项 签名 说明
XxxBuilder pub struct XxxBuilder<T> { ... } 与原 struct 同泛型,实现 Default
Xxx::builder() -> XxxBuilder<T> 入口构造器(已 Default::default())
XxxBuilder::new() -> Self 等价 Default::default()
with_<field>(v) mut self, value: impl Into<T> -> Self 普通 setter,字段上文档透传到 setter
with_<field>_option(opt) mut self, value: Option<T> -> Self 仅 Option<T> 字段生成,直接覆盖
<each_name>(v) mut self, value: impl Into<T> -> Self 仅 each 字段生成,追加元素
build(self) -> Result<Xxx<T>, String> 必填校验 + validate 钩子
try_build(self) -> Result<Xxx<T>, String> build 别名

字段处理规则:

  • Option<T> 字段:builder 内直接存 Option<T>(不双层嵌套),缺省即 None
  • 非 Option 非 each 字段:builder 内用 Option<T> 包装,缺省触发必填错误
  • each 字段:builder 内直接存 Vec<T>,缺省即空 Vec
  • skip 字段:不存于 builder,build 时用 Default::default()

性能优化

  • Builder 派生宏在编译期展开,运行时仅见生成代码;可测开销来自 Option 包装与必填校验,工程实践中可忽略
  • 容器宏 dict! / set! 使用 HashMap::with_capacity(N) / HashSet::with_capacity(N) 预分配容量(N = 字面量元素数),避免插入过程中多次 rehash
  • btree_dict! / btree_set! 保持 BTreeMap::new() / BTreeSet::new()(BTree 系无 with_capacity 方法)

示例 1:基础用法(必填 + 可选 + 默认)

use pyruts::Builder;

#[derive(Builder)]
struct Config {
    name: String,            // 必填
    age: u32,                // 必填
    #[builder(default)]
    email: Option<String>,   // 可选, 缺省 None
}

let c = Config::builder()
    .with_name("alice")
    .with_age(30u32)
    .with_email("a@x.com")   // 可选, 也可省略
    .build()
    .unwrap();

assert_eq!(c.name, "alice");
assert_eq!(c.email.as_deref(), Some("a@x.com"));

// 缺必填字段时返回 Err, 错误信息包含字段名
let err = Config::builder().with_name("a").build().unwrap_err();
assert!(err.contains("age"));

示例 2:validate 钩子 + each + default = "expr"

use pyruts::Builder;

fn check_range(c: &Validated) -> Result<(), String> {
    if c.age > 150 {
        return Err(format!("age {} exceeds human limit 150", c.age));
    }
    if c.name.is_empty() {
        return Err("name cannot be empty".into());
    }
    Ok(())
}

#[derive(Builder)]
#[builder(validate = "check_range")]
struct Validated {
    name: String,
    age: u32,
    #[builder(default = "vec![1, 2, 3]")]
    presets: Vec<i32>,
    #[builder(each = "tag")]
    tags: Vec<String>,
}

let v = Validated::builder()
    .with_name("alice")
    .with_age(30u32)
    .tag("admin")
    .tag("ops")
    .build()
    .unwrap();
assert_eq!(v.presets, vec![1, 2, 3]);
assert_eq!(v.tags, vec!["admin".to_string(), "ops".to_string()]);

// 校验失败: age 越界
let err = Validated::builder()
    .with_name("bob")
    .with_age(200u32)
    .build()
    .unwrap_err();
assert!(err.contains("exceeds human limit"));

示例 3:泛型 + where 子句 + 生命周期

use pyruts::Builder;

#[derive(Builder)]
struct GenericMulti<A, B> {
    a: A,
    b: B,
}

let g: GenericMulti<i32, String> = GenericMulti::builder()
    .with_a(1)
    .with_b("x".to_string())
    .build()
    .unwrap();

// where 子句
#[derive(Builder)]
struct WithWhereClause<T>
where
    T: Clone,
{
    data: T,
}

let g: WithWhereClause<i32> = WithWhereClause::builder()
    .with_data(42)
    .build()
    .unwrap();

// 泛型 + 生命周期
#[derive(Builder)]
struct WithLifetime<'a, T> {
    reference: &'a T,
    value: T,
}

let x = 42i32;
let g: WithLifetime<i32> = WithLifetime::builder()
    .with_reference(&x)
    .with_value(10)
    .build()
    .unwrap();
assert_eq!(*g.reference, 42);

示例 4:setter(strip_option) — 简化 Option 字段 API

Option<T> 字段默认会同时生成 with_xxx(impl Into<T>) 与 with_xxx_option(Option<T>) 两个 setter。若只想暴露前者(内部自动包 Some),用 setter(strip_option) 抑制后者。

use pyruts::Builder;

#[derive(Builder)]
struct User {
    name: String,
    // strip_option: 不生成 with_nick_option, 仅保留 with_nick(&str)
    #[builder(setter(strip_option))]
    nick: Option<String>,
}

let u = User::builder()
    .with_name("alice")
    .with_nick("ali")   // 直接传 &str, 内部包 Some
    .build()
    .unwrap();
assert_eq!(u.nick.as_deref(), Some("ali"));

// nick 未设置时缺省为 None
let u2 = User::builder().with_name("bob").build().unwrap();
assert!(u2.nick.is_none());

示例 5:field_defaults — 字段级默认配置

struct 级 field_defaults(...) 为所有字段设置默认配置,单字段可用 #[builder(...)] 覆盖。覆盖规则:字段级 Some(_) 优先,字段级未设置时回退到 struct 级。

use pyruts::Builder;

#[derive(Builder)]
#[builder(field_defaults(default = "0u32", skip = false))]
struct Counter {
    // 继承 field_defaults: default = "0u32"
    a: u32,
    // 字段级覆盖: default = "10u32"
    #[builder(default = "10u32")]
    b: u32,
    // 字段级覆盖: skip = true (build 时用 Default::default())
    #[builder(skip)]
    c: u32,
}

let x = Counter::builder().build().unwrap();
assert_eq!(x.a, 0);   // field_defaults 的 default
assert_eq!(x.b, 10);  // 字段级覆盖
assert_eq!(x.c, 0);   // skip → Default::default()

示例 6:builder_type(derive = "...") — 给 Builder 附加 derive

默认 XxxBuilder 只实现 Default。需要 Clone / Debug 等能力时,用 builder_type(derive = "...") 附加 #[derive(...)],逗号分隔多项。

use pyruts::Builder;

#[derive(Builder)]
#[builder(builder_type(derive = "Clone, Debug"))]
struct Config {
    host: String,
    port: u16,
}

let b = Config::builder().with_host("localhost").with_port(8080u16);
let _cloned = b.clone();    // Builder 现在实现 Clone
println!("{:?}", b);        // Builder 现在实现 Debug

示例 7:setter(prefix = "...") — 自定义 setter 前缀

默认 setter 名为 with_<field>。设 prefix = "" 后 setter 名直接等于字段名,调用形式更接近 Python 关键字参数;也可用任意前缀如 set_ 对齐 Java 风格。

use pyruts::Builder;

#[derive(Builder)]
#[builder(setter(prefix = ""))]
struct Config {
    name: String,
    age: u32,
}

// setter 名直接是字段名, 更接近 Python: Config(name="alice", age=30)
let c = Config::builder().name("alice").age(30u32).build().unwrap();
assert_eq!(c.name, "alice");
assert_eq!(c.age, 30);

c_wrap! 宏

c_wrap! 包装 extern "C" { ... } 块:原样输出链接声明,并为每个 C 函数生成 safe_<name> 安全包装函数,自动处理 *const c_char 转换和 buffer 模式。

行为说明

  • 原样输出 extern "C" { ... } 块(保留 FFI 链接声明)
  • 为每个函数生成 pub fn safe_<name>(...) -> ...:
    • unsafe 块收敛到生成代码内部,调用者无需写 unsafe
    • *const c_char 参数 → 接收 &str,内部 CString 转换(检测内部 NUL)
    • *const c_char 返回值 → 自动转 String(CStr 借用,不接管所有权)
    • (*mut c_char, usize) 参数对 → buffer 模式,safe 函数省略这两个参数,内部分配 4KB buffer 调用,返回 String
    • 末尾兜底 NUL,防止 C 函数漏写 NUL 导致越界读

参数类型转换规则

C 函数签名 safe 函数签名 转换策略
fn foo(x: i32) -> i32 fn safe_foo(x: i32) -> i32 原样透传
fn foo(s: *const c_char) -> i32 fn safe_foo(s: &str) -> i32 CString::new(s) → .as_ptr()
fn foo() -> *const c_char fn safe_foo() -> String CStr::from_ptr → .to_str().unwrap_or_default().to_owned()
fn foo(buf: *mut c_char, len: usize) -> usize fn safe_foo() -> String 内部分配 4KB buffer,末尾兜底 NUL,CStr 转 String
fn foo(p: *const c_char, buf: *mut c_char, len: usize) fn safe_foo(p: &str) -> String 普通参数 + buffer 对混合
fn foo() -> () fn safe_foo() 无返回值,直接调用
fn foo(s: Option<*const c_char>) fn safe_foo(s: Option<&str>) 可空指针,Some 时按 &str 转换
fn foo(arr: *const *const c_char) fn safe_foo(arr: &[&str]) 字符串数组

长度类型识别:usize / u64 / u32 / isize / i64 / i32 / size_t 均视为 buffer 长度参数。

示例 1:*const c_char 参数与返回值

use pyruts::c_wrap;
use std::os::raw::c_char;

// 用 #[no_mangle] Rust fn 模拟 C 函数
#[no_mangle]
pub extern "C" fn my_greet() -> *const c_char {
    b"hello\0".as_ptr() as *const c_char
}

#[no_mangle]
pub extern "C" fn my_echo(s: *const c_char) -> *const c_char {
    s  // 直接回传, 验证入参 &str → CString → ptr 链路
}

c_wrap! {
    extern "C" {
        fn my_greet() -> *const c_char;
        fn my_echo(s: *const c_char) -> *const c_char;
    }
}

// 生成的 safe_my_greet() -> String, safe_my_echo(&str) -> String
assert_eq!(safe_my_greet(), "hello");
assert_eq!(safe_my_echo("ping"), "ping");

// CString::new 检测内部 NUL, panic 信息含参数名
// safe_my_echo("a\0b");  // panic: CString::new failed for `s` (interior NUL byte)

示例 2:buffer 模式

use pyruts::c_wrap;
use std::os::raw::c_char;

#[no_mangle]
pub extern "C" fn my_get_str(buf: *mut c_char, len: usize) -> usize {
    let msg = b"hello world";
    let n = msg.len().min(len.saturating_sub(1));
    unsafe {
        std::ptr::copy_nonoverlapping(msg.as_ptr() as *const c_char, buf, n);
        *buf.add(n) = 0;
    }
    n
}

// 带 prefix 的混合签名: (普通 *const c_char) + (buffer 对)
#[no_mangle]
pub extern "C" fn my_get_prefixed(
    prefix: *const c_char,
    buf: *mut c_char,
    len: usize,
) -> usize {
    /* ... */
    0
}

c_wrap! {
    extern "C" {
        fn my_get_str(buf: *mut c_char, len: usize) -> usize;
        fn my_get_prefixed(prefix: *const c_char, buf: *mut c_char, len: usize) -> usize;
    }
}

// buffer 对被省略, safe 函数只接收普通参数
assert_eq!(safe_my_get_str(), "hello world");
assert_eq!(safe_my_get_prefixed("pre"), "pre+suffix");

// 即使 C 函数返回 i32, buffer 模式下 safe_ 仍返回 String

ensure! / bail! / throw!

对标 anyhow 生态的三个错误传播宏,返回 Err(format!(...).into()),与任何 From<String> 的错误类型兼容。

宏 语义 等价展开
ensure!(cond, msg, args...) 条件断言,!cond 时返回错误 if !(cond) { return Err(format!(msg, args...).into()); }
bail!(msg, args...) 立即返回错误 return Err(format!(msg, args...).into());
throw!(msg, args...) bail! 别名 同 bail!

示例

use pyruts::{ensure, bail, throw};

fn validate(x: i32, y: i32) -> Result<i32, String> {
    ensure!(x > 0, "x must be positive, got {}", x);
    ensure!(y > 0, "y must be positive, got {}", y);
    if x + y > 100 {
        bail!("sum {} too large", x + y);
    }
    if x == y {
        throw!("equal values not allowed: {}", x);
    }
    Ok(x + y)
}

assert_eq!(validate(5, 5).unwrap(), 10);
assert!(validate(-1, 5).is_err());
assert!(validate(60, 50).is_err());  // bail! 触发

短路求值

ensure! 条件为 true 时,错误消息参数不求值:

use pyruts::ensure;
use std::cell::Cell;

let called = Cell::new(false);
fn check(x: i32, flag: &Cell<bool>) -> Result<(), String> {
    flag.set(false);
    ensure!(x > 0, "got: {}", {
        flag.set(true);
        x * 2
    });
    Ok(())
}

assert!(check(5, &called).is_ok());
assert!(!called.get(), "cond=true 时错误消息参数不应被求值");

assert!(check(-1, &called).is_err());
assert!(called.get(), "cond=false 时错误消息参数应被求值");

dict! / btree_dict! / set! / btree_set!

用 k: v, k: v, ... 或 k => v, k => v, ... 语法构造 HashMap / BTreeMap,用 v, v, ... 语法构造 HashSet / BTreeSet,对标 maplit。

  • key 自动 .into()(仅 dict! / btree_dict!):适配 &str → String 等场景
  • value / set 元素原样保留:不调用 .into()
  • with_capacity 预分配:dict! / set! 使用 HashMap::with_capacity(N) / HashSet::with_capacity(N)(N = 字面量元素数),避免插入时多次 rehash;btree_dict! / btree_set! 因 BTree 系无 with_capacity 方法,保持 new()
  • trailing comma:四个宏均支持末尾逗号
  • 内部变量 __dict_map_inner / __set_inner:避免污染用户作用域
  • 双语法(仅 dict! / btree_dict!):: 原生风格,=> maplit 风格,二者等价

示例

use pyruts::{dict, btree_dict, set, btree_set};
use std::collections::{HashMap, BTreeMap, HashSet, BTreeSet};

// dict! — 原生 : 语法
let m: HashMap<String, i32> = dict! {
    "a": 1,
    "b": 2,
    "c": 3,
};
assert_eq!(m["a"], 1);

// dict! — maplit 风格 => 语法 (与 : 等价)
let m: HashMap<String, i32> = dict! {
    "a" => 1,
    "b" => 2,
};

// btree_dict! — 自动按 key 排序
let m: BTreeMap<&str, i32> = btree_dict! {
    "zebra": 1,
    "apple": 2,
    "mango": 3,
};
let keys: Vec<&str> = m.keys().copied().collect();
assert_eq!(keys, vec!["apple", "mango", "zebra"]);

// 空字典
let empty: HashMap<String, i32> = dict! {};
assert!(empty.is_empty());

// value 原样保留 (不 .into())
let m: BTreeMap<i32, String> = btree_dict! {
    1: String::from("one"),
    2: String::from("two"),
};

// set! — HashSet 字面量, with_capacity 预分配
let s: HashSet<i32> = set! { 1, 2, 3, };
assert_eq!(s.len(), 3);
assert!(s.contains(&2));

// btree_set! — BTreeSet 字面量, 自动按值排序
let s: BTreeSet<i32> = btree_set! { 3, 1, 2 };
let vals: Vec<&i32> = s.iter().collect();
assert_eq!(vals, vec![&1, &2, &3]);

// 空集合
let empty: HashSet<i32> = set! {};
assert!(empty.is_empty());

基准测试

benches/bench_main.rs 使用 criterion 对 9 个维度做对比,运行 cargo bench 即可:

基准组 对比项 说明
dict_vs_hashmap_from dict! vs HashMap::from([...]) 10 entry 字面量构造
btree_dict_vs_btreemap_from btree_dict! vs BTreeMap::from([...]) 10 entry 字面量构造
builder_vs_direct Builder::builder()...build() vs 直接字面量 3 字段构造
make_vs_builder_vs_direct make! vs Builder 链式 vs 直接字面量 make! 语法糖开销
dict_merge_vs_manual dict!(base; ...) vs 手动 extend vs 从零构造 字典合并开销
set_vs_hashset_from set! vs HashSet::from([...]) vs 手动 insert with_capacity 影响
builder_setter_prefix with_xxx vs xxx vs set_xxx setter 前缀 (期望零开销)
builder_strip_option 默认 vs setter(strip_option) Option 字段开销
field_defaults_vs_individual field_defaults vs 逐字段 default 配置方式 (期望零开销)

实测结果(Windows / criterion 0.5 / 100 样本均值)

基准组 函数 耗时 (ns)
dict_vs_hashmap_from dict_macro_10 880.6
hashmap_from_10 952.2
btree_dict_vs_btreemap_from btree_dict_macro_10 1166.4
btreemap_from_10 901.9
builder_vs_direct builder_construct 137.4
direct_construct 128.7
make_vs_builder_vs_direct make_macro 67.3
builder_chain 76.6
direct_literal 60.7
dict_merge_vs_manual dict_macro_merge 293.2
manual_merge 187.9
dict_from_scratch_3 173.3
set_vs_hashset_from set_macro_5 188.8
hashset_from_5 206.6
manual_insert_5 274.8
builder_setter_prefix prefix_with 40.7
prefix_empty 39.5
prefix_set 40.2
builder_strip_option default_option 50.6
strip_option 47.8
field_defaults_vs_individual field_defaults 0.23
individual_defaults 0.36

关键结论

零开销特性(编译期展开,运行时无差异):

  • setter(prefix):三种前缀(with_ / "" / set_)性能持平(39-41 ns),方法名在编译期决定,不影响运行时
  • field_defaults vs 逐字段 default:均为亚纳秒级(0.2-0.4 ns,约 1 cycle),编译器将常量构造完全折叠,两种配置方式生成等价代码
  • setter(strip_option):默认(50.6 ns)与 strip_option(47.8 ns)几乎相同,仅少生成一个 _option setter 方法,运行时执行路径一致

有可测开销的特性:

  • make! 宏(67.3 ns)vs 直接字面量(60.7 ns):make! 展开为 builder().with_xxx().build().expect(),多了 Option 包装与必填校验,约 11% 开销;与 Builder 链式(76.6 ns)持平甚至略快(单表达式更易内联)
  • dict!(base; ...) 合并(293.2 ns):显著慢于手动 extend(187.9 ns)与从零构造(173.3 ns)。原因:宏为支持 base 为表达式(而非仅变量),创建新 HashMap 并 extend(base) 复制,多一次分配与拷贝。若 base 已是变量,手动 let mut m = base; m.insert(...) 更快
  • set! 宏(188.8 ns)比 HashSet::from(206.6 ns)略快(约 9%),两者都 with_capacity 预分配;手动 insert 无预分配最慢(274.8 ns)
  • Builder 链式(137.4 ns)vs 直接字面量(128.7 ns):约 7% 开销,源于 Option 包装与必填校验

所有 proc_macro 特性在编译期展开,运行时只见生成代码。配置类属性(prefix / field_defaults / strip_option)经实测确认零运行时开销;仅 make!(语法糖,调用 builder)与 dict!(base;)(额外拷贝)有可测开销,但均在工程可接受范围。

运行单组基准:

cargo bench --bench bench_main -- dict_vs_hashmap_from

Python → Rust 迁移对照

下表把 Python 常见写法逐一映射到 pyruts 等价用法,便于从 Python 迁移或对照学习。make! 与 dict!(base; ...) 为规划中语法,未实现前请用右侧的 builder() / 手动 extend 等价写法。

Python pyruts Rust 说明
Config(name="a", age=30) make!(Config { name: "a", age: 30 }) 或 Config::builder().with_name("a").with_age(30).build().unwrap() 结构体构造
{"a": 1, "b": 2} dict! { "a" => 1, "b" => 2 } 或 dict! { "a": 1, "b": 2 } 字典字面量
{**base, "new": 1} dict!(base; "new" => 1) 字典合并
{"a", "b"} (set) set! { "a", "b" } 集合字面量
assert x > 0, "msg" ensure!(x > 0, "msg"); 断言
raise ValueError("msg") bail!("msg"); 抛出错误
try: ... except: ... let r = func()?; 或 match func() { Ok(_) => ..., Err(e) => ... } 错误处理
class Config: ... #[derive(Builder)] struct Config { ... } 类定义
@dataclass #[derive(Builder, Default)] struct Config { ... } 数据类
__post_init__ #[builder(validate = "fn")] 构造后校验
field(default=0) #[builder(default)] 或 #[builder(default = "0")] 默认值
field(default_factory=list) #[builder(default = "Vec::new()")] 默认工厂
Optional[str] = None field: Option<String> + #[builder(default)] 可选字段
List[int] + append Vec<i32> + #[builder(each = "item")] 列表追加
Config(name="a").rename("bob") #[builder(setter = "rename")] 方法重命名

迁移提示

  1. 静态类型 vs 动态类型:Rust 是静态类型,Python 是动态类型。pyruts 不能消除类型标注,但 #[derive(Builder)] 把样板代码压到一行 derive,配 setter(into) 让 &str 自动转 String,体验接近 Python 关键字参数。
  2. Result vs 异常:Rust 没有异常,错误用 Result<T, E> 表达。ensure! / bail! 是函数内 return Err(...) 的语法糖,不是 throw,跨函数传播必须靠 ? 或显式 match。
  3. Option vs None:Rust 没有 None 字面量,可空值用 Option<T>。Builder 的 Option<T> 字段缺省即 None,无需显式 = None,调用方未 set 即得 None。
  4. dict! vs dict literal:Rust 没有 dict 字面量,dict! 宏提供 : 与 => 两种语法,key 自动 .into() 适配 &str → String,with_capacity 预分配避免 rehash。
  5. 所有权 vs GC:Rust 没有 GC,所有权与生命周期必须显式管理。c_wrap! 生成的 safe_<name> 把 unsafe 收敛到生成代码内部,owned/free 模式自动 RAII 释放,避免手动 free 漏调。

设计哲学

  1. 零运行时开销:proc_macro 在编译期展开,不引入任何运行时类型或 trait object
  2. 向后兼容:所有生成 API 用绝对路径(::std::...),避免与用户 use 冲突;宏语义版本化,新增属性不破坏旧代码
  3. 最小依赖:仅依赖 syn / quote / proc-macro2 三件套,dev-dependencies 仅 libc 与 criterion
  4. unsafe 隔离:c_wrap! 把 FFI unsafe 收敛到生成代码内部,调用者只调 safe_<name>;buffer 模式末尾兜底 NUL,防御 C 函数漏写
  5. API 一致性:宏命名与语义严格对齐 anyhow / derive_builder / maplit,降低学习成本

MSRV

最低支持 Rust 1.70。CI 在 1.70 与 stable 双版本上跑测试。

License

MIT OR Apache-2.0,任选其一。