| Name | setuptools-rust JSON |
| Version |
1.9.0
JSON |
| download |
| home_page | |
| Summary | Setuptools Rust extension plugin |
| upload_time | 2024-02-24 15:45:23 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
distutils
setuptools
rust
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Setuptools plugin for Rust extensions
[](https://github.com/PyO3/setuptools-rust/actions/workflows/ci.yml)
[](https://pypi.org/project/setuptools-rust/)
[](https://setuptools-rust.readthedocs.io/en/latest/)
[](https://github.com/astral-sh/ruff)
`setuptools-rust` is a plugin for `setuptools` to build Rust Python extensions implemented with [PyO3](https://github.com/PyO3/pyo3) or [rust-cpython](https://github.com/dgrunwald/rust-cpython).
Compile and distribute Python extensions written in Rust as easily as if
they were written in C.
## Quickstart
The following is a very basic tutorial that shows how to use `setuptools-rust` in `pyproject.toml`.
It assumes that you already have a bunch of Python and Rust files that you want
to distribute. You can see examples for these files in the
[`examples/hello-world`](https://github.com/PyO3/setuptools-rust/tree/main/examples/hello-world)
directory in the [github repository](https://github.com/PyO3/setuptools-rust).
The [PyO3 docs](https://pyo3.rs) have detailed information on how to write Python
modules in Rust.
```
hello-world
├── python
│ └── hello_world
│ └── __init__.py
└── rust
└── lib.rs
```
Once the implementation files are in place, we need to add a `pyproject.toml`
file that tells anyone that wants to use your project how to build it.
In this file, we use an [array of tables](https://toml.io/en/v1.0.0#array-of-tables)
(TOML jargon equivalent to Python's list of dicts) for ``[[tool.setuptools-rust.ext-modules]]``,
to specify different extension modules written in Rust:
```toml
# pyproject.toml
[build-system]
requires = ["setuptools", "setuptools-rust"]
build-backend = "setuptools.build_meta"
[project]
name = "hello-world"
version = "1.0"
[tool.setuptools.packages]
# Pure Python packages/modules
find = { where = ["python"] }
[[tool.setuptools-rust.ext-modules]]
# Private Rust extension module to be nested into the Python package
target = "hello_world._lib" # The last part of the name (e.g. "_lib") has to match lib.name in Cargo.toml,
# but you can add a prefix to nest it inside of a Python package.
path = "Cargo.toml" # Default value, can be omitted
binding = "PyO3" # Default value, can be omitted
```
Each extension module should map directly into the corresponding `[lib]` table on the
[Cargo manifest file](https://doc.rust-lang.org/cargo/reference/manifest.html):
```toml
# Cargo.toml
[package]
name = "hello-world"
version = "0.1.0"
edition = "2021"
[dependencies]
pyo3 = "0.20.3"
[lib]
name = "_lib" # private module to be nested into Python package,
# needs to match the name of the function with the `[#pymodule]` attribute
path = "rust/lib.rs"
crate-type = ["cdylib"] # required for shared library for Python to import from.
# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
# See also PyO3 docs on writing Cargo.toml files at https://pyo3.rs
```
You will also need to tell Setuptools that the Rust files are required to build your
project from the [source distribution](https://setuptools.pypa.io/en/latest/userguide/miscellaneous.html).
That can be done either via `MANIFEST.in` (see example below) or via a plugin like
[`setuptools-scm`](https://pypi.org/project/setuptools-scm/).
```
# MANIFEST.in
include Cargo.toml
recursive-include rust *.rs
```
With these files in place, you can install the project in a virtual environment
for testing and making sure everything is working correctly:
```powershell
# cd hello-world
python3 -m venv .venv
source .venv/bin/activate # on Linux or macOS
.venv\Scripts\activate # on Windows
python -m pip install -e .
python
>>> import hello_world
# ... try running something from your new extension module ...
# ... better write some tests with pytest ...
```
## Next steps and final remarks
- When you are ready to distribute your project, have a look on
[the notes in the documentation about building wheels](https://setuptools-rust.readthedocs.io/en/latest/building_wheels.html).
- Cross-compiling is also supported, using one of
[`crossenv`](https://github.com/benfogle/crossenv),
[`cross`](https://github.com/rust-embedded/cross) or
[`cargo-zigbuild`](https://github.com/messense/cargo-zigbuild).
For examples see the `test-crossenv` and `test-cross` and `test-zigbuild` Github actions jobs in
[`ci.yml`](https://github.com/PyO3/setuptools-rust/blob/main/.github/workflows/ci.yml).
- You can also use `[[tool.setuptools-rust.bins]]` (instead of `[[tool.setuptools-rust.ext-modules]]`),
if you want to distribute a binary executable written in Rust (instead of a library that can be imported by the Python runtime).
Note however that distributing both library and executable (or multiple executables),
may significantly increase the size of the
[wheel](https://packaging.python.org/en/latest/glossary/#term-Wheel)
file distributed by the
[package index](https://packaging.python.org/en/latest/glossary/#term-Package-Index)
and therefore increase build, download and installation times.
Another approach is to use a Python entry-point that calls the Rust
implementation (exposed via PyO3 bindings).
See the [hello-world](https://github.com/PyO3/setuptools-rust/tree/main/examples/hello-world)
example for more insights.
- For a complete reference of the configuration options, see the
[API reference](https://setuptools-rust.readthedocs.io/en/latest/reference.html).
You can use any parameter defined by the `RustExtension` class with
`[[tool.setuptools-rust.ext-modules]]` and any parameter defined by the
`RustBin` class with `[[tool.setuptools-rust.bins]]`; just remember to replace
underscore characters `_` with dashes `-` in your `pyproject.toml` file.
- `Cargo.toml` allow only one `[lib]` table per file.
If you require multiple extension modules you will need to write multiple `Cargo.toml` files.
Alternatively you can create a single private Rust top-level module that exposes
multiple submodules (using [PyO3's submodules](https://pyo3.rs/v0.20.0/module#python-submodules)),
which may also reduce the size of the build artifacts.
You can always keep your extension modules private and wrap them in pure Python
to have fine control over the public API.
- If want to include both `[[tool.setuptools-rust.bins]]` and `[[tool.setuptools-rust.ext-modules]]`
in the same macOS wheel, you might have to manually add an extra `build.rs` file,
see [PyO3/setuptools-rust#351](https://github.com/PyO3/setuptools-rust/pull/351)
for more information about the workaround.
- For more examples, see:
- [`hello-world`](https://github.com/PyO3/setuptools-rust/tree/main/examples/hello-world):
a more complete version of the code used in this tutorial that mixes both
`[[tool.setuptools-rust.ext-modules]]` and `[[tool.setuptools-rust.bins]]`
in a single distribution.
- [`html-py-ever`](https://github.com/PyO3/setuptools-rust/tree/main/examples/html-py-ever):
a more advanced example that uses Rust crates as dependencies.
- [`rust_with_cffi`](https://github.com/PyO3/setuptools-rust/tree/main/examples/rust_with_cffi):
uses both Rust and [CFFI](https://cffi.readthedocs.io/en/latest/).
- [`namespace_package`](https://github.com/PyO3/setuptools-rust/tree/main/examples/namespace_package):
integrates Rust-written modules into PEP 420 namespace packages.
- [`hello-world-script`](https://github.com/PyO3/setuptools-rust/tree/main/examples/hello-world-script):
uses Rust only for creating binary executables, not library modules.
Raw data
{
"_id": null,
"home_page": "",
"name": "setuptools-rust",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "distutils,setuptools,rust",
"author": "",
"author_email": "Nikolay Kim <fafhrd91@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/9d/f1/2cb8887cad0726a5e429cc9c58e30767f58d22c34d55b075d2f845d4a2a5/setuptools-rust-1.9.0.tar.gz",
"platform": null,
"description": "# Setuptools plugin for Rust extensions\n\n[](https://github.com/PyO3/setuptools-rust/actions/workflows/ci.yml)\n[](https://pypi.org/project/setuptools-rust/)\n[](https://setuptools-rust.readthedocs.io/en/latest/)\n[](https://github.com/astral-sh/ruff)\n\n`setuptools-rust` is a plugin for `setuptools` to build Rust Python extensions implemented with [PyO3](https://github.com/PyO3/pyo3) or [rust-cpython](https://github.com/dgrunwald/rust-cpython).\n\nCompile and distribute Python extensions written in Rust as easily as if\nthey were written in C.\n\n## Quickstart\n\nThe following is a very basic tutorial that shows how to use `setuptools-rust` in `pyproject.toml`.\nIt assumes that you already have a bunch of Python and Rust files that you want\nto distribute. You can see examples for these files in the\n[`examples/hello-world`](https://github.com/PyO3/setuptools-rust/tree/main/examples/hello-world)\ndirectory in the [github repository](https://github.com/PyO3/setuptools-rust).\nThe [PyO3 docs](https://pyo3.rs) have detailed information on how to write Python\nmodules in Rust.\n\n```\nhello-world\n\u251c\u2500\u2500 python\n\u2502 \u2514\u2500\u2500 hello_world\n\u2502 \u2514\u2500\u2500 __init__.py\n\u2514\u2500\u2500 rust\n \u2514\u2500\u2500 lib.rs\n```\n\nOnce the implementation files are in place, we need to add a `pyproject.toml`\nfile that tells anyone that wants to use your project how to build it.\nIn this file, we use an [array of tables](https://toml.io/en/v1.0.0#array-of-tables)\n(TOML jargon equivalent to Python's list of dicts) for ``[[tool.setuptools-rust.ext-modules]]``,\nto specify different extension modules written in Rust:\n\n\n```toml\n# pyproject.toml\n[build-system]\nrequires = [\"setuptools\", \"setuptools-rust\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[project]\nname = \"hello-world\"\nversion = \"1.0\"\n\n[tool.setuptools.packages]\n# Pure Python packages/modules\nfind = { where = [\"python\"] }\n\n[[tool.setuptools-rust.ext-modules]]\n# Private Rust extension module to be nested into the Python package\ntarget = \"hello_world._lib\" # The last part of the name (e.g. \"_lib\") has to match lib.name in Cargo.toml,\n # but you can add a prefix to nest it inside of a Python package.\npath = \"Cargo.toml\" # Default value, can be omitted\nbinding = \"PyO3\" # Default value, can be omitted\n```\n\nEach extension module should map directly into the corresponding `[lib]` table on the\n[Cargo manifest file](https://doc.rust-lang.org/cargo/reference/manifest.html):\n\n```toml\n# Cargo.toml\n[package]\nname = \"hello-world\"\nversion = \"0.1.0\"\nedition = \"2021\"\n\n[dependencies]\npyo3 = \"0.20.3\"\n\n[lib]\nname = \"_lib\" # private module to be nested into Python package,\n # needs to match the name of the function with the `[#pymodule]` attribute\npath = \"rust/lib.rs\"\ncrate-type = [\"cdylib\"] # required for shared library for Python to import from.\n\n# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html\n# See also PyO3 docs on writing Cargo.toml files at https://pyo3.rs\n```\n\nYou will also need to tell Setuptools that the Rust files are required to build your\nproject from the [source distribution](https://setuptools.pypa.io/en/latest/userguide/miscellaneous.html).\nThat can be done either via `MANIFEST.in` (see example below) or via a plugin like\n[`setuptools-scm`](https://pypi.org/project/setuptools-scm/).\n\n```\n# MANIFEST.in\ninclude Cargo.toml\nrecursive-include rust *.rs\n```\n\nWith these files in place, you can install the project in a virtual environment\nfor testing and making sure everything is working correctly:\n\n```powershell\n# cd hello-world\npython3 -m venv .venv\nsource .venv/bin/activate # on Linux or macOS\n.venv\\Scripts\\activate # on Windows\npython -m pip install -e .\npython\n>>> import hello_world\n# ... try running something from your new extension module ...\n# ... better write some tests with pytest ...\n```\n\n## Next steps and final remarks\n\n- When you are ready to distribute your project, have a look on\n [the notes in the documentation about building wheels](https://setuptools-rust.readthedocs.io/en/latest/building_wheels.html).\n\n- Cross-compiling is also supported, using one of\n [`crossenv`](https://github.com/benfogle/crossenv),\n [`cross`](https://github.com/rust-embedded/cross) or\n [`cargo-zigbuild`](https://github.com/messense/cargo-zigbuild).\n For examples see the `test-crossenv` and `test-cross` and `test-zigbuild` Github actions jobs in\n [`ci.yml`](https://github.com/PyO3/setuptools-rust/blob/main/.github/workflows/ci.yml).\n\n- You can also use `[[tool.setuptools-rust.bins]]` (instead of `[[tool.setuptools-rust.ext-modules]]`),\n if you want to distribute a binary executable written in Rust (instead of a library that can be imported by the Python runtime).\n Note however that distributing both library and executable (or multiple executables),\n may significantly increase the size of the\n [wheel](https://packaging.python.org/en/latest/glossary/#term-Wheel)\n file distributed by the\n [package index](https://packaging.python.org/en/latest/glossary/#term-Package-Index)\n and therefore increase build, download and installation times.\n Another approach is to use a Python entry-point that calls the Rust\n implementation (exposed via PyO3 bindings).\n See the [hello-world](https://github.com/PyO3/setuptools-rust/tree/main/examples/hello-world)\n example for more insights.\n\n- For a complete reference of the configuration options, see the\n [API reference](https://setuptools-rust.readthedocs.io/en/latest/reference.html).\n You can use any parameter defined by the `RustExtension` class with\n `[[tool.setuptools-rust.ext-modules]]` and any parameter defined by the\n `RustBin` class with `[[tool.setuptools-rust.bins]]`; just remember to replace\n underscore characters `_` with dashes `-` in your `pyproject.toml` file.\n\n- `Cargo.toml` allow only one `[lib]` table per file.\n If you require multiple extension modules you will need to write multiple `Cargo.toml` files.\n Alternatively you can create a single private Rust top-level module that exposes\n multiple submodules (using [PyO3's submodules](https://pyo3.rs/v0.20.0/module#python-submodules)),\n which may also reduce the size of the build artifacts.\n You can always keep your extension modules private and wrap them in pure Python\n to have fine control over the public API.\n\n- If want to include both `[[tool.setuptools-rust.bins]]` and `[[tool.setuptools-rust.ext-modules]]`\n in the same macOS wheel, you might have to manually add an extra `build.rs` file,\n see [PyO3/setuptools-rust#351](https://github.com/PyO3/setuptools-rust/pull/351)\n for more information about the workaround.\n\n- For more examples, see:\n - [`hello-world`](https://github.com/PyO3/setuptools-rust/tree/main/examples/hello-world):\n a more complete version of the code used in this tutorial that mixes both\n `[[tool.setuptools-rust.ext-modules]]` and `[[tool.setuptools-rust.bins]]`\n in a single distribution.\n - [`html-py-ever`](https://github.com/PyO3/setuptools-rust/tree/main/examples/html-py-ever):\n a more advanced example that uses Rust crates as dependencies.\n - [`rust_with_cffi`](https://github.com/PyO3/setuptools-rust/tree/main/examples/rust_with_cffi):\n uses both Rust and [CFFI](https://cffi.readthedocs.io/en/latest/).\n - [`namespace_package`](https://github.com/PyO3/setuptools-rust/tree/main/examples/namespace_package):\n integrates Rust-written modules into PEP 420 namespace packages.\n - [`hello-world-script`](https://github.com/PyO3/setuptools-rust/tree/main/examples/hello-world-script):\n uses Rust only for creating binary executables, not library modules.\n",
"bugtrack_url": null,
"license": "",
"summary": "Setuptools Rust extension plugin",
"version": "1.9.0",
"project_urls": {
"Changelog": "https://github.com/PyO3/setuptools-rust/blob/main/CHANGELOG.md",
"Documentation": "https://setuptools-rust.readthedocs.io",
"Homepage": "https://github.com/PyO3/setuptools-rust",
"Repository": "https://github.com/PyO3/setuptools-rust"
},
"split_keywords": [
"distutils",
"setuptools",
"rust"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f77f8b1c33598b03ad612b8ced223f9ca54076b789fabf5a66ce37cc096d9cf7",
"md5": "d6d0645aa3e93c36b2394622805ce91b",
"sha256": "409caf49dcf7ad9bd510b4bf4011fbad504e745fae98f57fe1c06f3a97719638"
},
"downloads": -1,
"filename": "setuptools_rust-1.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d6d0645aa3e93c36b2394622805ce91b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 26608,
"upload_time": "2024-02-24T15:45:21",
"upload_time_iso_8601": "2024-02-24T15:45:21.529059Z",
"url": "https://files.pythonhosted.org/packages/f7/7f/8b1c33598b03ad612b8ced223f9ca54076b789fabf5a66ce37cc096d9cf7/setuptools_rust-1.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9df12cb8887cad0726a5e429cc9c58e30767f58d22c34d55b075d2f845d4a2a5",
"md5": "e3be6366d0d71304ca859edca3c89606",
"sha256": "704df0948f2e4cc60c2596ad6e840ea679f4f43e58ed4ad0c1857807240eab96"
},
"downloads": -1,
"filename": "setuptools-rust-1.9.0.tar.gz",
"has_sig": false,
"md5_digest": "e3be6366d0d71304ca859edca3c89606",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 311733,
"upload_time": "2024-02-24T15:45:23",
"upload_time_iso_8601": "2024-02-24T15:45:23.692620Z",
"url": "https://files.pythonhosted.org/packages/9d/f1/2cb8887cad0726a5e429cc9c58e30767f58d22c34d55b075d2f845d4a2a5/setuptools-rust-1.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-24 15:45:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PyO3",
"github_project": "setuptools-rust",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "setuptools-rust"
}
