uvによるPyO3プロジェクト

uvを使ってRustのpyo3プロジェクトを作成する 例。

概要

uvは、Pythonのプロジェクト管理を行うツール。

uvコマンドを使って、Rustを呼び出すPythonアプリケーションを作ることが出来る。

プロジェクトの作成

Windows11でサンプルプロジェクトを作る例。

uv init --python 3.14 --build-backend maturin example-pyo3

（生成されたCargo.tomlを見ると、pyo3のバージョンは0.27.1だった）

以下のようなディレクトリーとファイルが生成される。

• example-pyo3.
  • .gitignore
  • .python-version
  • Cargo.toml … Rust用のプロジェクト定義
  • pyproject.toml … Python用のプロジェクト定義
  • README.md …初期状態では空っぽ
  • src
    • lib.rs … Rustのプログラムの雛形
    • example_pyo3 … Pythonソースのディレクトリー
      • _core.pyi … IDE向けに関数の型の定義が記述されたファイルだそうだ
      • __init__.py … Pythonプログラムの雛形

初期生成されている雛形を実行することが出来る。
（「Hello from プロジェクト名!」という文字列が標準出力に出力される）

> cd example-pyo3
> uv run example-pyo3
Using CPython 3.14.2 interpreter at: C:\Users\〜\AppData\Local\Programs\Python\Python314\python.exe
Creating virtual environment at: .venv
      Built example-pyo3 @ file:///D:/tmp/rust/example-pyo3
〜
Hello from example-pyo3!

実行はvenvのPython仮想環境が使われるので、venvが初期化されていない場合は初期化される。
次いで、アプリケーションがビルドされていない場合は自動的にビルドされる。

雛形の構成

上記の手順で作ったプロジェクトに対して「uv run example-pyo3」というコマンドが実行されたとき、ソースコードとしては以下のような順序で呼ばれている（と思われる）。

pyproject.toml

pyproject.tomlに以下のようにスクリプトが定義されている。

〜
[project.scripts]
example-pyo3 = "example_pyo3:main"
〜

「example-pyo3 = "example_pyo3:main"」の左側が、uv runの引数で指定するスクリプト名。
「example-pyo3 = "example_pyo3:main"」の右側が、呼び出されるPyhonの関数。

なので「example = "example_pyo3:main"」にすると、「uv run example」で実行できるようになる。

src/example_pyo3/__init__.py

from example_pyo3._core import hello_from_bin

def main() -> None:
    print(hello_from_bin())

hello_from_binが、Rust側で定義されている関数。

from文にある「example_pyo3._core」は、src/example_pyo3/_core.pydファイルを指していると思われる。
（_core.pydファイルは、ビルドすると生成される）

なお、Pythonでは、アンダースコアが先頭に付いている識別子（変数名や関数名等）は、private（非公開）であることを意味する（慣例）。
「_core」は、内部で使用するコアモジュールという意味合いなのだろう。

src/lib.rs

Rust側はライブラリーなので、lib.rsに実装が書かれている。

use pyo3::prelude::*;

〜

#[pymodule]
mod _core {
    use pyo3::prelude::*;

    #[pyfunction]
    fn hello_from_bin() -> String {
        "Hello from example-pyo3!".to_string()
    }
}

pyo3のpymoduleやpyfunction属性を付けてモジュールや関数が定義されている。