在 Mojo 中与 Python…

编写 Mojo 与 Python 互操作代码（导入 Python 模块、转换类型、构建 Python 扩展模块、从 Python 调用 Mojo）时，用当前正确语法替代过时的预训练知识。

适用场景

解决思路

1. 导入 Python 模块使用 `from std.python import Python, PythonObject`（不是 `from python import ...`）。
2. 用 `Python.import_module("numpy")` 导入 Python 模块。
3. PythonObject 转 Mojo 类型时必须用 `py=` 关键字：`Int(py=py_obj)`、`Float64(py=py_obj)`、`String(py=py_obj)`；`Bool(py=py_obj)` 是例外，位置参数也可用。
4. 该转换也适用于 numpy 类型，如 `Int(py=np.int64(1))`、`Float64(py=np.float64(3.14))`。
5. Mojo 类型实现 `ConvertibleToPython` 时传给 Python 函数会自动转换；显式转换用 `value.to_python_object()`。
6. 构建 Python 集合：`Python.list(1, 2.5, "three")`、`Python.tuple(1, 2, 3)`、`Python.dict(name="value", count=42)`；也可用字面量语法 `var list_obj: PythonObject = [1, 2, 3]`、`var dict_obj: PythonObject = {"key": "value"}`。
7. `Python.dict()` 对所有 kwargs 泛型于单一值类型 V，混合类型会失败；需用 `Python.dict(flag=PythonObject(my_bool), count=PythonObject(42))` 显式包装。
8. PythonObject 支持属性访问、索引、切片、所有算术/比较运算符、`len()`、`in` 和迭代，均返回 PythonObject，中间操作无需转成 Mojo 类型。
9. 可直接迭代 Python 集合：`for item in py_list:`，item 为 PythonObject。
10. None 用 `Python.none()` 获取，或 `var obj: PythonObject = None` 隐式转换。
11. 求值 Python 表达式用 `Python.evaluate("1 + 2")`；多行代码作为模块用 `Python.evaluate("...", file=True)`。
12. 用 `Python.add_to_path("./my_modules")` 添加 Python 路径以导入本地模块。
13. Python 异常会作为 Mojo `Error` 传播，调用 Python 的函数必须标记 `raises`，用 `try/except e:` 捕获并 `String(e)` 打印。
14. 环境变量用 Mojo 原生 `from std.os import getenv` 和 `getenv("MY_VAR")`（返回 Optional[String]），不要用 Python os 模块。
15. Mojo 无 lambda 语法；需要自定义 key 排序时用 `Python.evaluate("lambda x: x['" + field + "']")` 生成可调用对象，再传给 `builtins.sorted(data, key=key_fn)`。
16. PythonObject 的 dict 可用 `.get()`：`data.get("name", PythonObject("unknown"))`，再 `Int(py=...)` 转换。
17. 构建 Python 扩展模块：定义 `@export def PyInit_<module_name>() abi("C") -> PythonObject`，用 `PythonModuleBuilder` 注册函数/类型/方法，用 `mojo build --emit shared-lib` 编译，从 Python 导入（或用 `import mojo.importer` 自动编译）。
18. 只有 `PyInit_<module>` 需要 `@export` 且必须 `abi("C")`，因为它被 CPython 运行时跨 C 边界直接调用，不能 `raises`，需捕获错误并 `abort`。
19. 用 `def_function`/`def_method` 注册的函数和方法按引用传递，无需 `@export`；Mojo 会用 C trampoline 包装并通过 Mojo ABI 调用，将抛出的错误转为 Python 异常，因此它们可以 `raises`。
20. 导出函数：在 `PyInit_` 中 `var m = PythonModuleBuilder("my_module")`，`m.def_function[add]("add")`，`return m.finalize()`；函数接收/返回 PythonObject，`def_function` 最多支持 6 个参数。
21. 导出类型：用 `m.add_type[Counter]("Counter").def_py_init[Counter.py_init]().def_method[Counter.increment]("increment").def_method[Counter.get_count]("get_count")` 链式注册。
22. 类型构造函数用 `@staticmethod def py_init(out self: Counter, args: PythonObject, kwargs: PythonObject) raises`，根据 `len(args)` 初始化。
23. 方法用 `@staticmethod`，有两种签名模式：手动 downcast 用 `py_self: PythonObject`（需原始 PythonObject 访问时），自动 downcast 用 `self_ptr: UnsafePointer[Self, MutAnyOrigin]`（更简单，直接字段访问）；两者都用 `.def_method[Type.method]("name")` 注册。
24. 手动 downcast 方法内用 `var self_ptr = py_self.downcast_value_ptr[Self]()` 获取指针，通过 `self_ptr[].field` 访问字段。
25. kwargs 支持：方法签名用 `kwargs: StringDict[PythonObject]`（`from std.collections import StringDict`），遍历 `kwargs.items()` 获取 `entry.key` 和 `entry.value`。
26. 从 Python 导入 Mojo 模块：`import mojo.importer` 后直接 `import my_module`，会自动编译并缓存到 `__mojocache__/`；`PyInit_<name>` 中的模块名必须与 `.mojo` 文件名匹配。
27. 作为共享库构建时 `.mojo` 文件不能包含 `main()` 函数，否则编译器报 `error: shared library should not contain a 'main' function`；测试/CLI 代码放在单独文件。
28. 返回 Mojo 值给 Python：用 `PythonObject(alloc=my_mojo_value^)` 转移所有权；之后用 `py_obj.downcast_value_ptr[MyType]()` 恢复并通过 `ptr[].field` 访问字段。

适用边界 · 注意事项

• 不涉及 Python 互操作的纯 Mojo 代码（应改用 mojo-syntax 技能）。
• 需要依赖过时 Mojo 语法或旧版 Python 绑定 API 的场景。