표3
PyO3 0.23.3
네이티브 Python 확장 모듈을 생성하기 위한 도구를 포함한 Python용 Rust 바인딩입니다. Rust 바이너리에서 Python 코드를 실행하고 상호 작용하는 것도 지원됩니다.
사용자 가이드: 안정적 | 기본
API 문서: 안정 | 기본
Rust 1.63 이상이 필요합니다.
PyO3는 다음 Python 배포판을 지원합니다:
PyO3를 사용하여 Rust에서 기본 Python 모듈을 작성하거나 Python을 Rust 바이너리에 포함할 수 있습니다. 다음 섹션에서는 이들 각각에 대해 차례로 설명합니다.
PyO3를 사용하여 기본 Python 모듈을 생성할 수 있습니다. 이것을 처음 시도하는 가장 쉬운 방법은 maturin 사용하는 것입니다. maturin 은 최소한의 구성으로 Rust 기반 Python 패키지를 빌드하고 게시하기 위한 도구입니다. 다음 단계에서는 maturin 설치하고 이를 사용하여 새 Python 패키지를 생성 및 빌드한 다음 Python을 시작하여 패키지에서 함수를 가져오고 실행합니다.
먼저, 아래 명령에 따라 새 Python virtualenv 포함된 새 디렉터리를 만들고 Python의 패키지 관리자인 pip 사용하여 maturin virtualenv에 설치합니다.
# (replace string_sum with the desired package name)
$ mkdir string_sum
$ cd string_sum
$ python -m venv .env
$ source .env/bin/activate
$ pip install maturin 여전히 이 string_sum 디렉토리 내에서 이제 maturin init 실행하십시오. 그러면 새 패키지 소스가 생성됩니다. 사용할 바인딩을 선택할 수 있으면 pyo3 바인딩을 선택하세요.
$ maturin init
✔ ? What kind of bindings to use ? · pyo3
Done ! New project created string_sum 이 명령으로 생성된 가장 중요한 파일은 Cargo.toml 및 lib.rs 이며 대략 다음과 같습니다.
Cargo.toml
[ package ]
name = " string_sum "
version = " 0.1.0 "
edition = " 2021 "
[ lib ]
# The name of the native library. This is the name which will be used in Python to import the
# library (i.e. `import string_sum`). If you change this, you must also change the name of the
# `#[pymodule]` in `src/lib.rs`.
name = " string_sum "
# "cdylib" is necessary to produce a shared library for Python to import from.
#
# Downstream Rust code (including code in `bin/`, `examples/`, and `tests/`) will not be able
# to `use string_sum;` unless the "rlib" or "lib" crate type is also included, e.g.:
# crate-type = ["cdylib", "rlib"]
crate-type = [ " cdylib " ]
[ dependencies ]
pyo3 = { version = " 0.23.3 " , features = [ " extension-module " ] } src/lib.rs
use pyo3 :: prelude :: * ;
/// Formats the sum of two numbers as string.
# [ pyfunction ]
fn sum_as_string ( a : usize , b : usize ) -> PyResult < String > {
Ok ( ( a + b ) . to_string ( ) )
}
/// A Python module implemented in Rust. The name of this function must match
/// the `lib.name` setting in the `Cargo.toml`, else Python will not be able to
/// import the module.
# [ pymodule ]
fn string_sum ( m : & Bound < ' _ , PyModule > ) -> PyResult < ( ) > {
m . add_function ( wrap_pyfunction ! ( sum_as_string , m ) ? ) ? ;
Ok ( ( ) )
} 마지막으로 maturin develop 실행하십시오. 그러면 패키지가 빌드되어 이전에 생성 및 활성화된 Python virtualenv에 설치됩니다. 그러면 python 에서 패키지를 사용할 준비가 되었습니다.
$ maturin develop
# lots of progress output as maturin runs the compilation...
$ python
>>> import string_sum
>>> string_sum.sum_as_string(5, 20)
' 25 ' 패키지를 변경하려면 Rust 소스 코드를 편집한 다음 maturin develop 다시 실행하여 다시 컴파일하면 됩니다.
이 모든 것을 단일 복사 및 붙여넣기로 실행하려면 아래 bash 스크립트를 사용하십시오(첫 번째 명령의 string_sum 원하는 패키지 이름으로 바꾸십시오).
mkdir string_sum && cd " $_ "
python -m venv .env
source .env/bin/activate
pip install maturin
maturin init --bindings pyo3
maturin develop cargo test 실행하거나 Cargo 작업 영역에서 이 프로젝트를 사용하고 싶은데 링커 문제가 발생하는 경우 FAQ에 몇 가지 해결 방법이 있습니다.
maturin 뿐만 아니라 setuptools-rust 사용하거나 수동으로 빌드하는 것도 가능합니다. 둘 다 maturin 보다 더 많은 유연성을 제공하지만 시작하려면 더 많은 구성이 필요합니다.
Python을 Rust 바이너리에 포함하려면 Python 설치에 공유 라이브러리가 포함되어 있는지 확인해야 합니다. 다음 단계에서는 이를 보장하는 방법(Ubuntu의 경우)을 보여주고 내장된 Python 인터프리터를 실행하는 몇 가지 예제 코드를 제공합니다.
Ubuntu에 Python 공유 라이브러리를 설치하려면:
sudo apt install python3-dev RPM 기반 배포판(예: Fedora, Red Hat, SuSE)에 Python 공유 라이브러리를 설치하려면 python3-devel 패키지를 설치하세요.
cargo new 로 새 프로젝트를 시작하고 다음과 같이 Cargo.toml 에 pyo3 추가합니다.
[ dependencies . pyo3 ]
version = " 0.23.3 "
features = [ " auto-initialize " ] sys.version 값과 현재 사용자 이름을 표시하는 예제 프로그램:
use pyo3 :: prelude :: * ;
use pyo3 :: types :: IntoPyDict ;
use pyo3 :: ffi :: c_str ;
fn main ( ) -> PyResult < ( ) > {
Python :: with_gil ( |py| {
let sys = py . import ( "sys" ) ? ;
let version : String = sys . getattr ( "version" ) ? . extract ( ) ? ;
let locals = [ ( "os" , py . import ( "os" ) ? ) ] . into_py_dict ( py ) ? ;
let code = c_str ! ( "os.getenv('USER') or os.getenv('USERNAME') or 'Unknown'" ) ;
let user : String = py . eval ( code , None , Some ( & locals ) ) ? . extract ( ) ? ;
println ! ( "Hello {}, I'm Python {}" , user , version ) ;
Ok ( ( ) )
} )
}가이드에는 이 주제에 대한 많은 예가 포함된 섹션이 있습니다.
built 크레이트로 얻은 메타데이터를 PyDict 로 노출하는 간단한 매크로PyO3에 기여하는 모든 분들을 환영합니다! 프로젝트를 지원하는 방법은 다음과 같이 다양합니다.
PyO3에 대한 자원 봉사 시간을 원하고 어디서부터 시작해야 할지 검색하고 있다면 우리의 기여 노트와 아키텍처 가이드에 더 많은 리소스가 있습니다.
직접 기여할 시간은 없지만 프로젝트의 향후 성공을 지원하고 싶다면 일부 관리자에게 GitHub 후원 페이지가 있습니다.
PyO3는 귀하의 선택에 따라 Apache-2.0 라이선스 또는 MIT 라이선스에 따라 라이선스가 부여됩니다.
Python은 Python 라이선스에 따라 라이선스가 부여됩니다.
귀하가 명시적으로 달리 명시하지 않는 한, Apache 라이선스에 정의된 대로 귀하가 PyO3에 포함하기 위해 의도적으로 제출한 기여는 추가 이용약관 없이 위와 같이 이중 라이선스가 부여됩니다.
