or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

commands.mdconfiguration.mdextension-building.mdindex.md
tile.json

tessl/pypi-setuptools-rust

Setuptools Rust extension plugin

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/setuptools-rust@1.12.x

To install, run

npx @tessl/cli install tessl/pypi-setuptools-rust@1.12.0

index.mddocs/

setuptools-rust

A setuptools plugin that provides seamless integration of Rust code into Python projects. It enables developers to build Python extensions written in Rust using PyO3 or rust-cpython bindings, compiling and distributing them as easily as C extensions.

Package Information

  • Package Name: setuptools-rust
  • Package Type: Python (setuptools plugin)
  • Language: Python
  • Installation: pip install setuptools-rust

Core Imports

from setuptools_rust import RustExtension, RustBin, Binding, Strip

For distutils commands:

from setuptools_rust import build_rust, clean_rust

Basic Usage

Using setup.py

from setuptools import setup
from setuptools_rust import RustExtension

setup(
    name="my-rust-extension",
    version="0.1.0",
    rust_extensions=[
        RustExtension(
            "my_extension.rust_module",  # Python module name
            path="Cargo.toml",           # Path to Cargo.toml
            binding=Binding.PyO3,        # Binding type
        )
    ],
    zip_safe=False,  # Rust extensions are not zip safe
)

Using pyproject.toml

[build-system]
requires = ["setuptools", "setuptools-rust"]

[[tool.setuptools-rust.ext-modules]]
target = "my_extension.rust_module"
path = "Cargo.toml"
binding = "PyO3"

[[tool.setuptools-rust.bins]]
target = "my-binary"
path = "Cargo.toml"

Architecture

setuptools-rust integrates with the Python packaging ecosystem through multiple layers:

  • Extension Configuration: RustExtension and RustBin classes define build targets and options
  • Build Commands: build_rust and clean_rust commands handle the Cargo build process
  • setuptools Integration: Entry points and hooks automatically integrate Rust building into standard Python packaging workflows
  • Cross-compilation Support: Full support for building across different target platforms

Capabilities

Extension Building

Configure and build Rust extensions as Python modules or standalone binaries. Supports multiple binding types (PyO3, rust-cpython, custom), cross-compilation, and extensive build customization.

class RustExtension:
    def __init__(
        self,
        target: Union[str, Dict[str, str]],
        path: str = "Cargo.toml",
        binding: Binding = Binding.PyO3,
        **kwargs
    ): ...

class RustBin(RustExtension):
    def __init__(
        self,
        target: Union[str, Dict[str, str]],
        path: str = "Cargo.toml",
        **kwargs
    ): ...

class Binding(IntEnum):
    PyO3 = auto()
    RustCPython = auto()
    NoBinding = auto()
    Exec = auto()

class Strip(IntEnum):
    No = auto()
    Debug = auto()
    All = auto()

Extension Building

Build Commands

Distutils commands for building and cleaning Rust extensions, with integration into standard Python packaging workflows.

class build_rust(RustCommand):
    description = "build Rust extensions (compile/link to build directory)"
    
    def run_for_extension(self, ext: RustExtension) -> None: ...
    def build_extension(
        self, 
        ext: RustExtension, 
        forced_target_triple: Optional[str] = None
    ) -> List[_BuiltModule]: ...

class clean_rust(RustCommand):
    description = "clean Rust extensions"
    
    def run_for_extension(self, ext: RustExtension) -> None: ...

Build Commands

Configuration Options

Comprehensive configuration through pyproject.toml files, supporting extension modules and binaries with full control over build options, features, and environment variables.

[[tool.setuptools-rust.ext-modules]]
target = "module_name"
path = "Cargo.toml"
binding = "PyO3"
features = ["feature1", "feature2"]
debug = false

[[tool.setuptools-rust.bins]]
target = "binary_name"
path = "Cargo.toml"
strip = "Debug"

Configuration

Types

from typing import Union, Dict, List, Optional, Sequence, Literal
from enum import IntEnum, auto

CargoMetadata = NewType("CargoMetadata", Dict[str, Any])

class Env:
    """Hashable wrapper for environment variable dictionaries."""

class SimpleSpec:
    """Parsed Rust version requirement specification."""

Environment Variables

Key environment variables that control the build process:

  • SETUPTOOLS_RUST_CARGO_PROFILE: Override cargo profile (e.g., "release", "dev")
  • CARGO_BUILD_TARGET: Set build target triple for cross-compilation
  • CARGO: Path to cargo executable
  • RUSTFLAGS: Additional flags passed to rustc compiler