跳到主要内容

MoonBit与Python集成指南

· 阅读需 13 分钟

引言​

Python，以其简洁的语法和庞大的生态系统，已成为当今最受欢迎的编程语言之一。然而，围绕其性能瓶颈和动态类型系统在大型项目中的维护性问题的讨论也从未停止。为了解决这些挑战，开发者社区探索了多种优化路径。

MoonBit 官方推出的 python.mbt 工具为此提供了一个新的视角。它允许开发者在 MoonBit 环境中直接调用 Python 代码。这种结合旨在融合 MoonBit 的静态类型安全、高性能潜力与 Python 成熟的生态系统。通过 python.mbt，开发者可以在享受 Python 丰富库函数的同时，利用 MoonBit 的静态分析能力、现代化的构建与测试工具，为构建大规模、高性能的系统级软件提供可能。

本文旨在深入探讨 python.mbt 的工作原理，并提供一份实践指南。本文将解答一些常见问题，例如：python.mbt 如何工作？它是否会因为增加了一个中间层而比原生 Python 更慢？相较于 C++ 的 pybind11 或 Rust 的 PyO3 等现有工具，python.mbt 的优势何在？要回答这些问题，我们首先需要理解 Python 解释器的基本工作流程。

Python 解释器的工作原理​

Python 解释器执行代码主要经历三个阶段：

  1. 解析阶段 (Parsing) ：此阶段包含词法分析和语法分析。解释器将人类可读的 Python 源代码分解成一个个标记（Token），然后根据语法规则将这些标记组织成一个树形结构，即抽象语法树（AST）。

    例如，对于以下 Python 代码：

    def add(x, y):
  return x + y

a = add(1, 2)
print(a)

    我们可以使用 Python 的 ast 模块来查看其生成的 AST 结构：

    Module(
    body=[
        FunctionDef(
            name='add',
            args=arguments(
                args=[
                    arg(arg='x'),
                    arg(arg='y')]),
            body=[
                Return(
                    value=BinOp(
                        left=Name(id='x', ctx=Load()),
                        op=Add(),
                        right=Name(id='y', ctx=Load())))]),
        Assign(
            targets=[
                Name(id='a', ctx=Store())],
            value=Call(
                func=Name(id='add', ctx=Load()),
                args=[
                    Constant(value=1),
                    Constant(value=2)])),
        Expr(
            value=Call(
                func=Name(id='print', ctx=Load()),
                args=[
                    Name(id='a', ctx=Load())]))])

  2. 编译阶段 (Compilation) ：接下来，Python 解释器会将 AST 编译成更低级、更线性的中间表示，即字节码（Bytecode）。这是一种平台无关的指令集，专为 Python 虚拟机（PVM）设计。

    利用 Python 的 dis 模块，我们可以查看上述代码对应的字节码：

      2           LOAD_CONST               0 (<code object add>)
              MAKE_FUNCTION
              STORE_NAME               0 (add)

  5           LOAD_NAME                0 (add)
              PUSH_NULL
              LOAD_CONST               1 (1)
              LOAD_CONST               2 (2)
              CALL                     2
              STORE_NAME               1 (a)

  6           LOAD_NAME                2 (print)
              PUSH_NULL
              LOAD_NAME                1 (a)
              CALL                     1
              POP_TOP
              RETURN_CONST             3 (None)

  3. 执行阶段 (Execution) ：最后，Python 虚拟机（PVM）会逐条执行字节码指令。每条指令都对应 CPython 解释器底层的一个 C 函数调用。例如，LOAD_NAME 会查找变量，BINARY_OP 会执行二元运算。正是这个逐条解释执行的过程，构成了 Python 性能开销的主要来源。一次简单的 1 + 2 运算，背后需要经历整个解析、编译和虚拟机执行的复杂流程。

了解这个流程，有助于我们理解 Python 性能优化的基本思路，以及 python.mbt 的设计哲学。

优化 Python 性能的路径​

目前，提升 Python 程序性能主要有两种主流方法：

  1. 即时编译（JIT） 。像 PyPy 这样的项目，通过分析正在运行的程序，将频繁执行的"热点"字节码编译成高度优化的本地机器码，从而绕过 PVM 的解释执行，大幅提升计算密集型任务的速度。然而，JIT 并非万能药，它无法解决 Python 动态类型语言的固有问题，例如在大型项目中难以进行有效的静态分析，这给软件维护带来了挑战。
  2. 原生扩展。开发者可以使用 C++（借助 pybind11）或 Rust（借助 PyO3）等语言直接调用Python功能，或者用这些语言来编写性能关键模块，然后从 Python 中调用。这种方法可以获得接近原生的性能，但它要求开发者同时精通 Python 和一门复杂的系统级语言，学习曲线陡峭，对大多数 Python 程序员来说门槛较高。

python.mbt 也是一种原生扩展。但相比较于C++和Rust等语言，它试图在性能、易用性和工程化能力之间找到一个新的平衡点，更强调在MoonBit语言中直接使用Python功能。

  1. 高性能核心：MoonBit 是一门静态类型的编译型语言，其代码可以被高效地编译成原生机器码。开发者可以将计算密集型逻辑用 MoonBit 实现，从根本上获得高性能。
  2. 无缝的 Python 调用：python.mbt 直接与 CPython 的 C-API 交互，调用 Python 模块和函数。这意味着调用开销被最小化，绕过了 Python 的解析和编译阶段，直达虚拟机执行层。
  3. 更平缓的学习曲线：相较于 C++ 和 Rust，MoonBit 的语法设计更加现代化和简洁，并拥有完善的函数式编程支持、文档系统、单元测试和静态分析工具，对习惯于 Python 的开发者更加友好。
  4. 改善的工程化与 AI 协作：MoonBit 的强类型系统和清晰的接口定义，使得代码意图更加明确，更易于被静态分析工具和 AI 辅助编程工具理解。这有助于在大型项目中维护代码质量，并提升与 AI 协作编码的效率和准确性。

在 MoonBit 中使用已封装的 Python 库​

为了方便开发者使用，MoonBit 官方会在构建系统和IDE成熟后对主流 Python 库进行封装。封装完成后，用户可以像导入普通 MoonBit 包一样，在项目中使用这些 Python 库。下面以 matplotlib 绘图库为例。

首先，在你的项目根目录的 moon.pkg.json 或终端中添加 matplotlib 依赖：

moon update
moon add Kaida-Amethyst/matplotlib

然后，在要使用该库的子包的 moon.pkg.json 中声明导入。这里，我们遵循 Python 的惯例，为其设置一个别名 plt：

{
  "import": [
    {
      "path": "Kaida-Amethyst/matplotlib",
      "alias": "plt"
    }
  ]
}

完成配置后，便可以在 MoonBit 代码中调用 matplotlib 进行绘图：

let 
(Double) -> Double
sin : (
Double
Double) -> 
Double
Double = 
(x : Double) -> Double
Calculates the sine of a number in radians. Handles special cases and edge
conditions according to IEEE 754 standards.
Parameters:
    

  • x : The angle in radians for which to calculate the sine.
    • 

Returns the sine of the angle x.
Example:
inspect(@math.sin(0.0), content="0")
inspect(@math.sin(1.570796326794897), content="1") // pi / 2
inspect(@math.sin(2.0), content="0.9092974268256817")
inspect(@math.sin(-5.0), content="0.9589242746631385")
inspect(@math.sin(31415926535897.9323846), content="0.0012091232715481885")
inspect(@math.sin(@double.not_a_number), content="NaN")
inspect(@math.sin(@double.infinity), content="NaN")
inspect(@math.sin(@double.neg_infinity), content="NaN")
@math.sin

fn main {
  let 
Array[Double]
x = 
type Array[T]
An Array is a collection of values that supports random access and can
grow in size.
Array::
(Int, (Int) -> Double) -> Array[Double]
Creates a new array of the specified length, where each element is
initialized using an index-based initialization function.
Parameters:
    

  • length : The length of the new array. If length is less than or equal
to 0, returns an empty array.
    • 

  • initializer : A function that takes an index (starting from 0) and
returns a value of type T. This function is called for each index to
initialize the corresponding element.
    • 

Returns a new array of type Array[T] with the specified length, where each
element is initialized using the provided function.
Example:
  let arr = Array::makei(3, i => i * 2)
  inspect(arr, content="[0, 2, 4]")
makei(100, fn(
Int
i) { 
Int
i.
(self : Int) -> Double
Converts a 32-bit integer to a double-precision floating-point number. The
conversion preserves the exact value since all integers in the range of Int
can be represented exactly as Double values.
Parameters:
    

  • self : The 32-bit integer to be converted.
    • 

Returns a double-precision floating-point number that represents the same
numerical value as the input integer.
Example:
  let n = 42
  inspect(n.to_double(), content="42")
  let neg = -42
  inspect(neg.to_double(), content="-42")
to_double() 
(self : Double, other : Double) -> Double
Multiplies two double-precision floating-point numbers. This is the
implementation of the * operator for Double type.
Parameters:
    

  • self : The first double-precision floating-point operand.
    • 

  • other : The second double-precision floating-point operand.
    • 

Returns a new double-precision floating-point number representing the product
of the two operands. Special cases follow IEEE 754 standard:
    

  • If either operand is NaN, returns NaN
    • 

  • If one operand is infinity and the other is zero, returns NaN
    • 

  • If one operand is infinity and the other is a non-zero finite number,
returns infinity with the appropriate sign
    • 

  • If both operands are infinity, returns infinity with the appropriate sign
    • 

Example:
  inspect(2.5 * 2.0, content="5")
  inspect(-2.0 * 3.0, content="-6")
  let nan = 0.0 / 0.0 // NaN
  inspect(nan * 1.0, content="NaN")
* 0.1 })
  let 
Array[Double]
y = 
Array[Double]
x.
(self : Array[Double], f : (Double) -> Double) -> Array[Double]
Maps a function over the elements of the array.
Example
  let v = [3, 4, 5]
  let v2 = v.map((x) => {x + 1})
  assert_eq(v2, [4, 5, 6])
map(
(Double) -> Double
sin)

  // 为保证类型安全，封装后的 subplots 接口总是返回一个固定类型的元组。
  // 这避免了 Python 中根据参数返回不同类型对象的动态行为。
  let (_, 
Unit
axes) = 
(Int, Int) -> (Unit, Unit)
plt::subplots(1, 1)

  // 使用 .. 级联调用语法
  
Unit
axes[0
(Int) -> Unit
][0]
  ..
(Array[Double], Array[Double], Unit, Unit, Int) -> Unit
plot(
Array[Double]
x, 
Array[Double]
y, 
Unit
color = 
Unit
Green, 
Unit
linestyle = 
Unit
Dashed, 
Int
linewidth = 2)
  ..
(String) -> Unit
set_title("Sine of x")
  ..
(String) -> Unit
set_xlabel("x")
  ..
(String) -> Unit
set_ylabel("sin(x)")

  
() -> Unit
@plt.show()
}

目前，在 macOS 和 Linux 环境下，MoonBit 的构建系统可以自动处理依赖。在 Windows 上，用户可能需要手动安装 C 编译器并配置 Python 环境。未来的 MoonBit IDE 将致力于简化这一过程。

在 MoonBit 中使用未封装的 Python 模块​

Python 生态浩如烟海，即使现在有了AI技术，完全依赖官方封装也并不现实。幸运的是，我们可以利用 python.mbt 的核心功能直接与任何 Python 模块交互。下面，我们以 Python 标准库中，一个简单的的 time 模块为例，演示这一过程。

引入 python.mbt​

首先，确保你的 MoonBit 工具链是最新版本，然后添加 python.mbt 依赖：

moon update
moon add Kaida-Amethyst/python

接着，在你的包的 moon.pkg.json 中导入它：

{
  "import": ["Kaida-Amethyst/python"]
}

python.mbt 会自动处理 Python 解释器的初始化（Py_Initialize）和关闭，开发者无需手动管理。

导入 Python 模块​

使用 @python.pyimport 函数来导入模块。为了避免重复导入造成的性能损耗，建议使用闭包技巧来缓存导入的模块对象：

// 定义一个结构体来持有 Python 模块对象，增强类型安全
pub struct TimeModule {
  
?
time_mod: PyModule
}

// 定义一个函数，它返回一个闭包，该闭包用于获取 TimeModule 实例
fn 
() -> () -> TimeModule
import_time_mod() -> () -> 
struct TimeModule {
  time_mod: ?
}
TimeModule {
  // 仅在首次调用时执行导入操作
  guard 
(String) -> Unit
@python.pyimport("time") is 
(?) -> Unit
Some(
?
time_mod) else {
    
(input : String) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:
    

  • value : The value to be printed. Must implement the Show trait.
    • 

Example:
  println(42)
  println("Hello, World!")
  println([1, 2, 3])
println("Failed to load Python module: time")
    
() -> () -> TimeModule
panic("ModuleLoadError")
  }
  let 
TimeModule
time_mod = 
struct TimeModule {
  time_mod: ?
}
TimeModule::{ 
?
time_mod }
  // 返回的闭包会捕获 time_mod 变量
  fn () { 
TimeModule
time_mod }
}

// 创建一个全局的 time_mod "getter" 函数
let 
() -> TimeModule
time_mod: () -> 
struct TimeModule {
  time_mod: ?
}
TimeModule = 
() -> () -> TimeModule
import_time_mod()

在后续代码中，我们应始终通过调用 time_mod() 来获取模块，而不是 import_time_mod。

MoonBit 与 Python 对象的相互转换​

要调用 Python 函数，我们需要在 MoonBit 对象和 Python 对象（PyObject）之间进行转换。

  1. 整数: 使用 PyInteger::from 从 Int64 创建 PyInteger，使用 to_int64() 反向转换。

    test "py_integer_conversion" {
  let 
    Int64
    n    : 
    Int64
    Int64     = 42    
  let 
    &Show
    py_int     = 
    (Int64) -> &Show
    PyInteger::from    (
    Int64
    n    )    
  
    (obj : &Show, content~ : String, loc~ : SourceLoc = _, args_loc~ : ArgsLoc = _) -> Unit raise InspectError
    Tests if the string representation of an object matches the expected content.
Used primarily in test cases to verify the correctness of Show
implementations and program outputs.
    Parameters:
      

    • object : The object to be inspected. Must implement the Show trait.
      • 

    • content : The expected string representation of the object. Defaults to
an empty string.
      • 

    • location : Source code location information for error reporting.
Automatically provided by the compiler.
      • 

    • arguments_location : Location information for function arguments in
source code. Automatically provided by the compiler.
      • 

    Throws an InspectError if the actual string representation of the object
does not match the expected content. The error message includes detailed
information about the mismatch, including source location and both expected
and actual values.
    Example:
      inspect(42, content="42")
  inspect("hello", content="hello")
  inspect([1, 2, 3], content="[1, 2, 3]")
    inspect    (
    &Show
    py_int    , 
    String
    content    ="42")    
  
    (a : Int64, b : Int64, msg? : String, loc~ : SourceLoc = _) -> Unit raise
    Asserts that two values are equal. If they are not equal, raises a failure
with a message containing the source location and the values being compared.
    Parameters:
      

    • a : First value to compare.
      • 

    • b : Second value to compare.
      • 

    • loc : Source location information to include in failure messages. This is
usually automatically provided by the compiler.
      • 

    Throws a Failure error if the values are not equal, with a message showing
the location of the failing assertion and the actual values that were
compared.
    Example:
      assert_eq(1, 1)
  assert_eq("hello", "hello")
    assert_eq    (
    &Show
    py_int    .
    () -> Int64
    to_int64    (), 42L)    
}

  2. 浮点数: 使用 PyFloat::from 和 to_double。

    test "py_float_conversion" {
  let 
    Double
    n    : 
    Double
    Double     = 3.5    
  let 
    &Show
    py_float     = 
    (Double) -> &Show
    PyFloat::from    (
    Double
    n    )    
  
    (obj : &Show, content~ : String, loc~ : SourceLoc = _, args_loc~ : ArgsLoc = _) -> Unit raise InspectError
    Tests if the string representation of an object matches the expected content.
Used primarily in test cases to verify the correctness of Show
implementations and program outputs.
    Parameters:
      

    • object : The object to be inspected. Must implement the Show trait.
      • 

    • content : The expected string representation of the object. Defaults to
an empty string.
      • 

    • location : Source code location information for error reporting.
Automatically provided by the compiler.
      • 

    • arguments_location : Location information for function arguments in
source code. Automatically provided by the compiler.
      • 

    Throws an InspectError if the actual string representation of the object
does not match the expected content. The error message includes detailed
information about the mismatch, including source location and both expected
and actual values.
    Example:
      inspect(42, content="42")
  inspect("hello", content="hello")
  inspect([1, 2, 3], content="[1, 2, 3]")
    inspect    (
    &Show
    py_float    , 
    String
    content    ="3.5")    
  
    (a : Double, b : Double, msg? : String, loc~ : SourceLoc = _) -> Unit raise
    Asserts that two values are equal. If they are not equal, raises a failure
with a message containing the source location and the values being compared.
    Parameters:
      

    • a : First value to compare.
      • 

    • b : Second value to compare.
      • 

    • loc : Source location information to include in failure messages. This is
usually automatically provided by the compiler.
      • 

    Throws a Failure error if the values are not equal, with a message showing
the location of the failing assertion and the actual values that were
compared.
    Example:
      assert_eq(1, 1)
  assert_eq("hello", "hello")
    assert_eq    (
    &Show
    py_float    .
    () -> Double
    to_double    (), 3.5)    
}

  3. 字符串: 使用 PyString::from 和 to_string。

    test "py_string_conversion" {
  let 
    &Show
    py_str     = 
    (String) -> &Show
    PyString::from    ("hello")    
  
    (obj : &Show, content~ : String, loc~ : SourceLoc = _, args_loc~ : ArgsLoc = _) -> Unit raise InspectError
    Tests if the string representation of an object matches the expected content.
Used primarily in test cases to verify the correctness of Show
implementations and program outputs.
    Parameters:
      

    • object : The object to be inspected. Must implement the Show trait.
      • 

    • content : The expected string representation of the object. Defaults to
an empty string.
      • 

    • location : Source code location information for error reporting.
Automatically provided by the compiler.
      • 

    • arguments_location : Location information for function arguments in
source code. Automatically provided by the compiler.
      • 

    Throws an InspectError if the actual string representation of the object
does not match the expected content. The error message includes detailed
information about the mismatch, including source location and both expected
and actual values.
    Example:
      inspect(42, content="42")
  inspect("hello", content="hello")
  inspect([1, 2, 3], content="[1, 2, 3]")
    inspect    (
    &Show
    py_str    , 
    String
    content    ="'hello'")    
  
    (a : String, b : String, msg? : String, loc~ : SourceLoc = _) -> Unit raise
    Asserts that two values are equal. If they are not equal, raises a failure
with a message containing the source location and the values being compared.
    Parameters:
      

    • a : First value to compare.
      • 

    • b : Second value to compare.
      • 

    • loc : Source location information to include in failure messages. This is
usually automatically provided by the compiler.
      • 

    Throws a Failure error if the values are not equal, with a message showing
the location of the failing assertion and the actual values that were
compared.
    Example:
      assert_eq(1, 1)
  assert_eq("hello", "hello")
    assert_eq    (
    &Show
    py_str    .
    (&Show) -> String
    to_string    (), "hello")    
}

  4. 列表 (List) : 你可以创建一个空 PyList 然后 append 元素，或者直接从一个 Array[&IsPyObject] 创建。

    test "py_list_from_array" {
  let 
    Unit
    one     = 
    (Int) -> Unit
    PyInteger::from    (1)    
  let 
    Unit
    two     = 
    (Double) -> Unit
    PyFloat::from    (2.0)    
  let 
    Unit
    three     = 
    (String) -> Unit
    PyString::from    ("three")    
  let 
    Array[Unit]
    arr
    Array[Unit]
    : 
    type Array[T]
    An Array is a collection of values that supports random access and can
grow in size.
    Array
    Array[Unit]
    [&IsPyObject]     = [
    Unit
    one    , 
    Unit
    two    , 
    Unit
    three    ]    

  let 
    &Show
    list     = 
    (Array[Unit]) -> &Show
    PyList::from    (
    Array[Unit]
    arr    )    
  
    (obj : &Show, content~ : String, loc~ : SourceLoc = _, args_loc~ : ArgsLoc = _) -> Unit raise InspectError
    Tests if the string representation of an object matches the expected content.
Used primarily in test cases to verify the correctness of Show
implementations and program outputs.
    Parameters:
      

    • object : The object to be inspected. Must implement the Show trait.
      • 

    • content : The expected string representation of the object. Defaults to
an empty string.
      • 

    • location : Source code location information for error reporting.
Automatically provided by the compiler.
      • 

    • arguments_location : Location information for function arguments in
source code. Automatically provided by the compiler.
      • 

    Throws an InspectError if the actual string representation of the object
does not match the expected content. The error message includes detailed
information about the mismatch, including source location and both expected
and actual values.
    Example:
      inspect(42, content="42")
  inspect("hello", content="hello")
  inspect([1, 2, 3], content="[1, 2, 3]")
    inspect    (
    &Show
    list    , 
    String
    content    ="[1, 2.0, 'three']")    
}

  5. 元组 (Tuple) : PyTuple 需要先指定大小，然后通过 set 方法逐一填充元素。

    test "py_tuple_creation" {
  let 
    &Show
    tuple     = 
    (Int) -> &Show
    PyTuple::new    (3)    
  
    &Show
    tuple    
  ..
    (Int, Unit) -> Unit
    set    (0, 
    (Int) -> Unit
    PyInteger::from    (1))    
  ..
    (Int, Unit) -> Unit
    set    (1, 
    (Double) -> Unit
    PyFloat::from    (2.0))    
  ..
    (Int, Unit) -> Unit
    set    (2, 
    (String) -> Unit
    PyString::from    ("three"))    

  
    (obj : &Show, content~ : String, loc~ : SourceLoc = _, args_loc~ : ArgsLoc = _) -> Unit raise InspectError
    Tests if the string representation of an object matches the expected content.
Used primarily in test cases to verify the correctness of Show
implementations and program outputs.
    Parameters:
      

    • object : The object to be inspected. Must implement the Show trait.
      • 

    • content : The expected string representation of the object. Defaults to
an empty string.
      • 

    • location : Source code location information for error reporting.
Automatically provided by the compiler.
      • 

    • arguments_location : Location information for function arguments in
source code. Automatically provided by the compiler.
      • 

    Throws an InspectError if the actual string representation of the object
does not match the expected content. The error message includes detailed
information about the mismatch, including source location and both expected
and actual values.
    Example:
      inspect(42, content="42")
  inspect("hello", content="hello")
  inspect([1, 2, 3], content="[1, 2, 3]")
    inspect    (
    &Show
    tuple    , 
    String
    content    ="(1, 2.0, 'three')")    
}

  6. 字典 (Dict) : PyDict 主要支持字符串作为键。使用 new 创建字典，set 添加键值对。对于非字符串键，需要使用 set_by_obj。

    test "py_dict_creation" {
  let 
    &Show
    dict     = 
    () -> &Show
    PyDict::new    ()    
  
    &Show
    dict    
  ..
    (String, Unit) -> Unit
    set    ("one", 
    (Int) -> Unit
    PyInteger::from    (1))    
  ..
    (String, Unit) -> Unit
    set    ("two", 
    (Double) -> Unit
    PyFloat::from    (2.0))    

  
    (obj : &Show, content~ : String, loc~ : SourceLoc = _, args_loc~ : ArgsLoc = _) -> Unit raise InspectError
    Tests if the string representation of an object matches the expected content.
Used primarily in test cases to verify the correctness of Show
implementations and program outputs.
    Parameters:
      

    • object : The object to be inspected. Must implement the Show trait.
      • 

    • content : The expected string representation of the object. Defaults to
an empty string.
      • 

    • location : Source code location information for error reporting.
Automatically provided by the compiler.
      • 

    • arguments_location : Location information for function arguments in
source code. Automatically provided by the compiler.
      • 

    Throws an InspectError if the actual string representation of the object
does not match the expected content. The error message includes detailed
information about the mismatch, including source location and both expected
and actual values.
    Example:
      inspect(42, content="42")
  inspect("hello", content="hello")
  inspect([1, 2, 3], content="[1, 2, 3]")
    inspect    (
    &Show
    dict    , 
    String
    content    ="{'one': 1, 'two': 2.0}")    
}

从 Python 复合类型中获取元素时，python.mbt 会进行运行时类型检查，并返回一个 Optional[PyObjectEnum]，以确保类型安全。

test "py_list_get" {
  let 
Unit
list = 
() -> Unit
PyList::new()
  
Unit
list.
(Unit) -> Unit
append(
(Int) -> Unit
PyInteger::from(1))
  
Unit
list.
(Unit) -> Unit
append(
(String) -> Unit
PyString::from("hello"))

  
(obj : &Show, content~ : String, loc~ : SourceLoc = _, args_loc~ : ArgsLoc = _) -> Unit raise InspectError
Tests if the string representation of an object matches the expected content.
Used primarily in test cases to verify the correctness of Show
implementations and program outputs.
Parameters:
    

  • object : The object to be inspected. Must implement the Show trait.
    • 

  • content : The expected string representation of the object. Defaults to
an empty string.
    • 

  • location : Source code location information for error reporting.
Automatically provided by the compiler.
    • 

  • arguments_location : Location information for function arguments in
source code. Automatically provided by the compiler.
    • 

Throws an InspectError if the actual string representation of the object
does not match the expected content. The error message includes detailed
information about the mismatch, including source location and both expected
and actual values.
Example:
  inspect(42, content="42")
  inspect("hello", content="hello")
  inspect([1, 2, 3], content="[1, 2, 3]")
inspect(
Unit
list.
(Int) -> Unit
get(0).
() -> &Show
unwrap(), 
String
content="PyInteger(1)")
  
(obj : &Show, content~ : String, loc~ : SourceLoc = _, args_loc~ : ArgsLoc = _) -> Unit raise InspectError
Tests if the string representation of an object matches the expected content.
Used primarily in test cases to verify the correctness of Show
implementations and program outputs.
Parameters:
    

  • object : The object to be inspected. Must implement the Show trait.
    • 

  • content : The expected string representation of the object. Defaults to
an empty string.
    • 

  • location : Source code location information for error reporting.
Automatically provided by the compiler.
    • 

  • arguments_location : Location information for function arguments in
source code. Automatically provided by the compiler.
    • 

Throws an InspectError if the actual string representation of the object
does not match the expected content. The error message includes detailed
information about the mismatch, including source location and both expected
and actual values.
Example:
  inspect(42, content="42")
  inspect("hello", content="hello")
  inspect([1, 2, 3], content="[1, 2, 3]")
inspect(
Unit
list.
(Int) -> Unit
get(1).
() -> &Show
unwrap(), 
String
content="PyString('hello')")
  
(obj : &Show, content~ : String, loc~ : SourceLoc = _, args_loc~ : ArgsLoc = _) -> Unit raise InspectError
Tests if the string representation of an object matches the expected content.
Used primarily in test cases to verify the correctness of Show
implementations and program outputs.
Parameters:
    

  • object : The object to be inspected. Must implement the Show trait.
    • 

  • content : The expected string representation of the object. Defaults to
an empty string.
    • 

  • location : Source code location information for error reporting.
Automatically provided by the compiler.
    • 

  • arguments_location : Location information for function arguments in
source code. Automatically provided by the compiler.
    • 

Throws an InspectError if the actual string representation of the object
does not match the expected content. The error message includes detailed
information about the mismatch, including source location and both expected
and actual values.
Example:
  inspect(42, content="42")
  inspect("hello", content="hello")
  inspect([1, 2, 3], content="[1, 2, 3]")
inspect(
Unit
list.
(Int) -> &Show
get(2), 
String
content="None") // 索引越界返回 None
}

调用模块中的函数​

调用函数分为两步：首先用 get_attr 获取函数对象，然后用 invoke 执行调用。invoke 的返回值是一个需要进行模式匹配和类型转换的 PyObject。

下面是 time.sleep 和 time.time 的 MoonBit 封装：

// 封装 time.sleep
pub fn 
(seconds : Double) -> Unit
sleep(
Double
seconds: 
Double
Double) -> 
Unit
Unit {
  let 
TimeModule
lib = 
() -> TimeModule
time_mod()
  guard 
TimeModule
lib.
?
time_mod.
(String) -> Unit
get_attr("sleep") is 
(_/0) -> Unit
Some(
(Unit) -> _/0
PyCallable(
Unit
f)) else {
    
(input : String) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:
    

  • value : The value to be printed. Must implement the Show trait.
    • 

Example:
  println(42)
  println("Hello, World!")
  println([1, 2, 3])
println("get function `sleep` failed!")
    
() -> Unit
panic()
  }
  let 
Unit
args = 
(Int) -> Unit
PyTuple::new(1)
  
Unit
args.
(Int, Unit) -> Unit
set(0, 
(Double) -> Unit
PyFloat::from(
Double
seconds))
  match (try? 
Unit
f.
(Unit) -> Unit
invoke(
Unit
args)) {
    
(Unit) -> Result[Unit, Error]
Ok(_) => 
Unit
Ok(())
    
(Error) -> Result[Unit, Error]
Err(
Error
e) => {
      
(input : String) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:
    

  • value : The value to be printed. Must implement the Show trait.
    • 

Example:
  println(42)
  println("Hello, World!")
  println([1, 2, 3])
println("invoke `sleep` failed!")
      
() -> Unit
panic()
    }
  }
}

// 封装 time.time
pub fn 
() -> Double
time() -> 
Double
Double {
  let 
TimeModule
lib = 
() -> TimeModule
time_mod()
  guard 
TimeModule
lib.
?
time_mod.
(String) -> Unit
get_attr("time") is 
(_/0) -> Unit
Some(
(Unit) -> _/0
PyCallable(
Unit
f)) else {
    
(input : String) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:
    

  • value : The value to be printed. Must implement the Show trait.
    • 

Example:
  println(42)
  println("Hello, World!")
  println([1, 2, 3])
println("get function `time` failed!")
    
() -> Double
panic()
  }
  match (try? 
Unit
f.
() -> Unit
invoke()) {
    
(Unit) -> Result[Unit, Error]
Ok(
(_/0) -> Unit
Some(
(Unit) -> _/0
PyFloat(
Unit
t))) => 
Unit
t.
() -> Double
to_double()
    _ => {
      
(input : String) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:
    

  • value : The value to be printed. Must implement the Show trait.
    • 

Example:
  println(42)
  println("Hello, World!")
  println([1, 2, 3])
println("invoke `time` failed!")
      
() -> Double
panic()
    }
  }
}

完成封装后，我们就可以在 MoonBit 中以类型安全的方式使用它们了：

test "sleep" {
  let 
Unit
start = 
() -> Double
time().
() -> Unit
unwrap()
  
(seconds : Double) -> Unit
sleep(1)
  let 
Unit
end = 
() -> Double
time().
() -> Unit
unwrap()

  
(input : String) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:
    

  • value : The value to be printed. Must implement the Show trait.
    • 

Example:
  println(42)
  println("Hello, World!")
  println([1, 2, 3])
println("start = \{
Unit
start}")
  
(input : String) -> Unit
Prints any value that implements the Show trait to the standard output,
followed by a newline.
Parameters:
    

  • value : The value to be printed. Must implement the Show trait.
    • 

Example:
  println(42)
  println("Hello, World!")
  println([1, 2, 3])
println("end = \{
Unit
end}")
}

实践建议​

  1. 明确边界：将 python.mbt 视为连接 MoonBit 和 Python 生态的"胶水层"。将核心计算和业务逻辑保留在 MoonBit 中以利用其性能和类型系统优势，仅在必要情况下，需要调用 Python 独有库时才使用 python.mbt。

  2. 用 ADT 替代字符串魔法：许多 Python 函数接受特定的字符串作为参数来控制行为。在 MoonBit 封装中，应将这些"魔法字符串"转换为代数数据类型（ADT） ，即枚举。这利用了 MoonBit 的类型系统，将运行时的值检查提前到编译时，极大地增强了代码的健壮性。

  3. 完善的错误处理：本文中的示例为了简洁使用了 panic 或返回简单字符串。在生产代码中，应定义专门的错误类型，并通过 Result 类型进行传递和处理，提供清晰的错误上下文。

  4. 映射关键字参数：Python 函数广泛使用关键字参数（kwargs），如 plot(color='blue', linewidth=2)。这可以优雅地映射到 MoonBit 的标签参数（Labeled Arguments） 。在封装时，应优先使用标签参数以提供相似的开发体验。

    例如，一个接受 kwargs 的 Python 函数：

    # graphics.py
def draw_line(points, color="black", width=1):
    # ... drawing logic ...
    print(f"Drawing line with color {color} and width {width}")

    其 MoonBit 封装可以设计成：

    fn draw_line(points: Array[Point], color~: Color = Black, width: Int = 1) -> Unit {
  let points : PyList = ... // convert Array[Point] to PyList

  // 构造args
  let args = PyTuple::new(1)
  args .. set(0, points)

  // 构造kwargs
  let kwargs = PyDict::new()
  kwargs
  ..set("color", PyString::from(color))
  ...set("width", PyInteger::from(width))
  match (try? f.invoke(args~, kwargs~)) {
    Ok(_) => ()
    _ => {
      // 进行错误处理
    }
  }
}

  5. 警惕动态性：始终牢记 Python 是动态类型的。从 Python 获取的任何数据都应被视为"不可信"的，必须进行严格的类型检查和校验，尽量避免使用 unwrap，而是通过模式匹配来安全地处理所有可能的情况。

结语​

本文梳理了 python.mbt 的工作原理，并展示了如何利用它在 MoonBit 中调用 Python 代码，无论是通过预封装的库还是直接与 Python 模块交互。python.mbt 不仅仅是一个工具，它代表了一种融合思想：将 MoonBit 的静态分析、高性能和工程化优势与 Python 庞大而成熟的生态系统相结合。我们希望这篇文章能为 MoonBit 和 Python 社区的开发者们在构建未来软件时，提供一个新的、更强大的选择。