Rust for Python Programmers | Rust 面向 Python 程序员

Rust Modules vs Python Packages
Rust 模块系统与 Python 包系统对照

What you’ll learn: mod and use vs import, visibility (pub) vs Python’s convention-based privacy, Cargo.toml vs pyproject.toml, crates.io vs PyPI, and workspaces vs monorepos.
本章将学到什么： mod 和 use 与 Python import 的对应关系，pub 可见性与 Python 约定式私有的差别，Cargo.toml 与 pyproject.toml 的角色对照，crates.io 与 PyPI 的区别，以及 Rust workspace 和 Python monorepo 的不同。

Difficulty: 🟢 Beginner
难度： 🟢 入门

Python Module System
Python 的模块系统

# Python — files are modules, directories with __init__.py are packages

# myproject/
# ├── __init__.py          # Makes it a package
# ├── main.py
# ├── utils/
# │   ├── __init__.py      # Makes utils a sub-package
# │   ├── helpers.py
# │   └── validators.py
# └── models/
#     ├── __init__.py
#     ├── user.py
#     └── product.py

# Importing:
from myproject.utils.helpers import format_name
from myproject.models.user import User
import myproject.utils.validators as validators

Python 这套东西的特点是“默认能跑，靠约定成形”。文件天然就是模块，目录里有 __init__.py 就成了包。学起来轻松，结构也灵活。
但灵活的另一面就是边界偏松，公开不公开、应该从哪里导入、哪些名字只给内部用，很多时候都靠团队自觉。

Rust Module System
Rust 的模块系统

#![allow(unused)]
fn main() {
// Rust — mod declarations create the module tree, files provide content

// src/
// ├── main.rs             # Crate root — declares modules
// ├── utils/
// │   ├── mod.rs           # Module declaration (like __init__.py)
// │   ├── helpers.rs
// │   └── validators.rs
// └── models/
//     ├── mod.rs
//     ├── user.rs
//     └── product.rs

// In src/main.rs:
mod utils;       // Tells Rust to look for src/utils/mod.rs
mod models;      // Tells Rust to look for src/models/mod.rs

use utils::helpers::format_name;
use models::user::User;

// In src/utils/mod.rs:
pub mod helpers;      // Declares and re-exports helpers.rs
pub mod validators;   // Declares and re-exports validators.rs
}

graph TD
    A["main.rs<br/>(crate root)"] --> B["mod utils"]
    A --> C["mod models"]
    B --> D["utils/mod.rs"]
    D --> E["helpers.rs"]
    D --> F["validators.rs"]
    C --> G["models/mod.rs"]
    G --> H["user.rs"]
    G --> I["product.rs"]
    style A fill:#d4edda,stroke:#28a745
    style D fill:#fff3cd,stroke:#ffc107
    style G fill:#fff3cd,stroke:#ffc107

Python equivalent: Think of mod.rs as __init__.py — it declares what the module exports. The crate root (main.rs / lib.rs) is like your top-level package __init__.py.
和 Python 的类比： 可以把 mod.rs 看成 __init__.py，负责声明模块要暴露什么。crate 根，也就是 main.rs 或 lib.rs，则类似顶层包的 __init__.py。

Rust 的模块系统更明确，也更啰嗦一点。模块树不是靠目录结构自动脑补出来的，而是要用 mod 明明白白声明。
这套设计刚上手时会觉得有点拧巴，但好处是边界更稳定，导出关系更清楚，工程越大越有味道。

Key Differences
核心差异

Visibility — Private by Default
可见性：默认私有

# Python — "we're all adults here"
class User:
    def __init__(self):
        self.name = "Alice"       # Public (by convention)
        self._age = 30            # "Private" (convention: single underscore)
        self.__secret = "shhh"    # Name-mangled (not truly private)

# Nothing stops you from accessing _age or even __secret
print(user._age)                  # Works fine
print(user._User__secret)        # Works too (name mangling)

#![allow(unused)]
fn main() {
// Rust — private is enforced by the compiler
pub struct User {
    pub name: String,      // Public — anyone can access
    age: i32,              // Private — only this module can access
}

impl User {
    pub fn new(name: &str, age: i32) -> Self {
        User { name: name.to_string(), age }
    }

    pub fn age(&self) -> i32 {   // Public getter
        self.age
    }

    fn validate(&self) -> bool { // Private method
        self.age > 0
    }
}

// Outside the module:
let user = User::new("Alice", 30);
println!("{}", user.name);        // ✅ Public
// println!("{}", user.age);      // ❌ Compile error: field is private
println!("{}", user.age());       // ✅ Public method (getter)
}

这就是 Python 和 Rust 在“边界感”上的经典差别。Python 更像是在说：大家都是成年人，别乱碰。Rust 则直接说：哪些能碰，哪些不能碰，编译器提前写死。
写小脚本时前者很轻巧，写大工程时后者通常更省心，因为模块接口和内部实现分得更干净。

Crates vs PyPI Packages
crate 与 PyPI 包

Python Packages (PyPI)
Python 包与 PyPI

# Python
pip install requests           # Install from PyPI
pip install "requests>=2.28"   # Version constraint
pip freeze > requirements.txt  # Lock versions
pip install -r requirements.txt # Reproduce environment

Rust Crates (crates.io)
Rust crate 与 crates.io

# Rust
cargo add reqwest              # Install from crates.io (adds to Cargo.toml)
cargo add reqwest@0.12         # Version constraint
# Cargo.lock is auto-generated — no manual step
cargo build                    # Downloads and compiles dependencies

Python 的依赖管理历史包袱比较重，requirements.txt、setup.py、pyproject.toml、poetry、uv 各有各的玩法。Rust 这边基本统一交给 Cargo，体验就利索很多。
至少在“声明依赖、锁版本、复现环境”这件事上，Cargo 默认就把主流程打通了。

Cargo.toml vs pyproject.toml
Cargo.toml 与 pyproject.toml 对照

# Rust — Cargo.toml
[package]
name = "my-project"
version = "0.1.0"
edition = "2021"

[dependencies]
serde = { version = "1.0", features = ["derive"] }  # With feature flags
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["full"] }
log = "0.4"

[dev-dependencies]
mockall = "0.13"

pyproject.toml 更像 Python 世界逐步统一后的汇总入口，而 Cargo.toml 则从一开始就是 Rust 项目管理的中心。包信息、依赖、特性开关、构建入口，几乎都围着它转。
所以很多 Python 开发者第一次用 Cargo 时会有种感觉：这玩意怎么什么都给安排好了。

Essential Crates for Python Developers
Python 开发者常见库在 Rust 里的对应物

这张表并不是说“Python 库 A 完全等于 Rust 库 B”，而是帮忙建立迁移时的直觉地图。
很多时候 Rust 生态的抽象方式和 Python 不完全一样，但先知道该从哪块地找，效率会高很多。

Workspaces vs Monorepos
workspace 与 monorepo

Python Monorepo (typical)
典型的 Python monorepo

# Python monorepo (various approaches, no standard)
myproject/
├── pyproject.toml           # Root project
├── packages/
│   ├── core/
│   │   ├── pyproject.toml   # Each package has its own config
│   │   └── src/core/...
│   ├── api/
│   │   ├── pyproject.toml
│   │   └── src/api/...
│   └── cli/
│       ├── pyproject.toml
│       └── src/cli/...
# Tools: poetry workspaces, pip -e ., uv workspaces — no standard

Rust Workspace
Rust workspace

# Rust — Cargo.toml at root
[workspace]
members = [
    "core",
    "api",
    "cli",
]

# Shared dependencies across workspace
[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

# Rust workspace structure — standardized, built into Cargo
myproject/
├── Cargo.toml               # Workspace root
├── Cargo.lock               # Single lock file for all crates
├── core/
│   ├── Cargo.toml            # [dependencies] serde.workspace = true
│   └── src/lib.rs
├── api/
│   ├── Cargo.toml
│   └── src/lib.rs
└── cli/
    ├── Cargo.toml
    └── src/main.rs

# Workspace commands
cargo build                  # Build everything
cargo test                   # Test everything
cargo build -p core          # Build just the core crate
cargo test -p api            # Test just the api crate
cargo clippy --all           # Lint everything

Key insight: Rust workspaces are first-class, built into Cargo. Python monorepos require third-party tools (poetry, uv, pants) with varying levels of support. In a Rust workspace, all crates share a single Cargo.lock, ensuring consistent dependency versions across the project.
关键理解： Rust workspace 是 Cargo 原生支持的一等能力。Python monorepo 往往需要额外工具来拼装，而且不同方案支持程度差异不小。Rust workspace 下所有 crate 共用一个 Cargo.lock，依赖版本一致性更容易维持。

如果已经习惯 Python 大仓库那种“一堆工具互相套娃”的日常，第一次用 Rust workspace 时通常会有点舒服过头。因为它本来就是官方设计的一部分，不用再自己东拼西凑。
这也是 Rust 工程化体验比较整齐的一个重要原因。

Exercises
练习

mod kitchen {
    fn secret_recipe() -> &'static str { "42 spices" }
    pub fn menu() -> &'static str { "Today's special" }

    pub mod staff {
        pub fn cook() -> String {
            format!("Cooking with {}", super::secret_recipe())
        }
    }
}

fn main() {
    println!("{}", kitchen::menu());             // Line A
    println!("{}", kitchen::secret_recipe());     // Line B
    println!("{}", kitchen::staff::cook());       // Line C
}