Crate Python

Embedding Python ecosystem into Rust

This crate enable any dependent crate contains a fully-featured python project, which can depend on other crates python project, or any legal python package.

The python project and its dependency will be solved and carried along when the rust project being built, then runed by embbed python executable.

Why

Many softwares like Unreal, Blender, Houdini, has embedded python so that user can extend it.

However, its hard to add third party python package or specify python version. Say multiple plugins might depend on a same package like numpy, there is no way to resolve them into one single dependency.

The key point is that these software lack a python package manager. So this project come into being, to bring a python package manager into Rust, with custom python executable to embed.

Overview

• any crate after using this become a python crate, which can contain a python project.
• python crate can be furthur devided into python lib crate and python bin crate.
• python lib crate must and only be depended by python crate, python bin crate must not be depend by python crate.
• there should only be one python bin crate in a rust project.
• after rust project is built, all python projects inside python crate can be avaliable using pyo3.

Dependency

• based on pyo3 and pdm, a python is required to run pdm and another one to embed by pyo3.
• internet access to download pdm if you don't have one, and download python package.

Add this crate

cargo add --git https://github.com/windwhiterain/crate_python.git crate_python

Use this crate

example project

Config a python lib crate

• place crate_python::config!{<has python>,<dependencies>} at the root module of the crate.
  • replace <has python> with a bool value to specify weather this crate contains a python project.
  • replace <dependencies> with any number of python lib crate's name that this crate depend on, e.g. crate_a, crate_b.

Config a python bin crate

• place crate_python::config!{<dependencies>} at the build script of the crate.
• call crate_python_build_bin() in the build script. this function is generated by the config! macro.

Optional: Add a python project to python crate

• the path to the python project must be fixed to <crate directory>/python
• since we use pdm, we suggest you using pdm to manage this python project too.

Add cargo config

• add PYO3_PYTHON = <path to your python.exe>, where pyo3 will find the python executable to embed.
• add CRATE_PYTHON_DEV = "0" | "1". when this is set to "1" we perform faster build but can not distribute, otherwise slow but ready to distribute.

Build

• cargo run with CRATE_PYTHON_DEV set to "1" to development.
• cargo build --release with CRATE_PYTHON_DEV set to "0" to distribute.

  • at target/release, besides the executable, you can found:

    • python<X><Y>.dll, X, Y are the python major and minner version.
    • Lib/
    • python_project/

    pack all of them with the executable

Access Python in Rust

• call crate_python::init() before using pyo3.
• see pyo3: call python from rust.
• every python crate's python project can be import.

Note

• be cautious to activate generated virtual environmnet, they might be removed during build so that pdm might find a broken python to create virtual environment.