ITADN

feat: Python bindings via PyO3 + Cargo workspace restructure

#158ClosedKingTimer12 创建于 2026-05-11
enhancementpriority: medium
K
KingTimer12commented
### Search before asking - [x] I have searched the Ultralytics [issues](https://github.com/ultralytics/PROJECT_NAME/issues) and found no similar feature requests. ### Description Add official Python bindings to `ultralytics-inference` via PyO3, delivered as a Cargo workspace restructure. The repo splits into two crates — `crates/ultralytics-inference` (existing library + CLI, unchanged) and `crates/ultralytics-pyo3` (new `cdylib` extension) — plus a `py-inference/` Python package built with maturin. A `cdylib` crate-type cannot coexist with `rlib`/`bin` in the same package, making the workspace restructure a technical requirement, not an optional refactor. ### Use case Python is the dominant language in the computer-vision ecosystem and Ultralytics' primary audience. Today, Python users who want the performance of this Rust inference engine have no official path: they must either shell out to the CLI or reimplement the pipeline in Python. Native bindings close that gap with a clean, Pythonic API: ```python from ultralytics_inference import YOLO model = YOLO("yolo11n.onnx") results = model.predict("https://ultralytics.com/images/bus.jpg", conf=0.25, imgsz=640) # also works with files, directories, globs, and batch lists results = model.predict("images/*.jpg", conf=0.5, save=True) results = model.predict(["img1.jpg", "img2.jpg"]) ``` The workspace layout also future-proofs the repo for Node.js and WebAssembly support: a single `crates/ultralytics-napi` member using [napi-rs](https://napi.rs) would cover both targets (napi-rs supports native Node.js addons and `wasm32` from one crate) without touching the core library. ### Additional A working implementation is ready as a draft PR. It includes: - Zero breaking changes to the existing Rust public API - Single version bump point via `[workspace.package]` - `[workspace.lints]` enforcing `clippy::pedantic` + `missing_docs` across all members - `.pyi` stubs via `maturin generate-stubs` for IDE type support - Rust integration tests for the pyo3 crate (no Python interpreter required) - Python unit tests via pytest with a conftest stub (run without a compiled extension) Happy to iterate on the design before the PR is opened if the team has preferences around the API surface or packaging approach. ### Are you willing to submit a PR? - [x] Yes I'd like to help by submitting a PR!
关闭于 2026-05-11 2 条评论