API Reference#

class setuptools_rust.RustExtension(target, path='Cargo.toml', args=(), cargo_manifest_args=(), features=(), rustc_flags=(), rust_version=None, quiet=False, debug=None, binding=Binding.PyO3, strip=Strip.No, script=False, native=False, optional=False, py_limited_api='auto')#

Used to define a rust extension module and its build configuration.

Parameters:

  • target (Union[str, Dict[str, str]]) – The full Python dotted name of the extension, including any packages, i.e not a filename or pathname. It is possible to specify multiple binaries, if extension uses Binding.Exec binding mode. In that case first argument has to be dictionary. Keys of the dictionary correspond to the rust binary names and values are the full dotted name to place the executable inside the python package. To install executables with kebab-case names, the final part of the dotted name can be in kebab-case. For example, hello_world.hello-world will install an executable named hello-world.

  • path (str) – Path to the Cargo.toml manifest file.

  • args (Optional[Sequence[str]]) – A list of extra arguments to be passed to Cargo. For example, args=["--no-default-features"] will disable the default features listed in Cargo.toml.

  • cargo_manifest_args (Optional[Sequence[str]]) – A list of extra arguments to be passed to Cargo. These arguments will be passed to every cargo command, not just cargo build. For valid options, see the Cargo Book. For example, cargo_manifest_args=["--locked"] will require Cargo.lock files are up to date.

  • features (Optional[Sequence[str]]) – Cargo –features to add to the build.

  • rustc_flags (Optional[Sequence[str]]) – A list of additional flags passed to cargo rustc. These only affect the final artifact, usually you should set the RUSTFLAGS environment variable.

  • rust_version (Optional[str]) – Minimum Rust compiler version required for this extension.

  • quiet (bool) – Suppress Cargo’s output.

  • debug (Optional[bool]) – Controls whether --debug or --release is passed to Cargo. If set to None (the default) then build type is automatic: inplace build will be a debug build, install and wheel builds will be release.

  • binding (Binding) – Informs setuptools_rust which Python binding is in use.

  • strip (Strip) – Strip symbols from final file. Does nothing for debug build.

  • native (bool) – Build extension or executable with -Ctarget-cpu=native (deprecated, set environment variable RUSTFLAGS=-Ctarget-cpu=native).

  • script (bool) – Generate console script for executable if Binding.Exec is used (deprecated, just use RustBin instead).

  • optional (bool) – If it is true, a build failure in the extension will not abort the build process, and instead simply not install the failing extension.

  • py_limited_api (Literal['auto', True, False]) – Deprecated.

class setuptools_rust.RustBin(target, path='Cargo.toml', args=(), cargo_manifest_args=(), features=(), rust_version=None, quiet=False, debug=None, strip=Strip.No, optional=False)#

Used to define a Rust binary and its build configuration.

Parameters:

  • target (Union[str, Dict[str, str]]) – Rust binary target name.

  • path (str) – Path to the Cargo.toml manifest file.

  • args (Optional[Sequence[str]]) – A list of extra arguments to be passed to Cargo. For example, args=["--no-default-features"] will disable the default features listed in Cargo.toml.

  • cargo_manifest_args (Optional[Sequence[str]]) –

    A list of extra arguments to be passed to Cargo. These arguments will be passed to every cargo command, not just cargo build. For valid options, see the Cargo Book. For example, cargo_manifest_args=["--locked"] will require Cargo.lock files are up to date.

  • features (Optional[Sequence[str]]) – Cargo –features to add to the build.

  • rust_version (Optional[str]) – Minimum Rust compiler version required for this bin.

  • quiet (bool) – Suppress Cargo’s output.

  • debug (Optional[bool]) – Controls whether --debug or --release is passed to Cargo. If set to None (the default) then build type is automatic: inplace build will be a debug build, install and wheel builds will be release.

  • strip (Strip) – Strip symbols from final file. Does nothing for debug build.

  • optional (bool) – If it is true, a build failure in the bin will not abort the build process, and instead simply not install the failing bin.

class setuptools_rust.Binding(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Enumeration of possible Rust binding types supported by setuptools-rust.

PyO3#

This is an extension built using PyO3.

RustCPython#

This is an extension built using rust-cpython.

NoBinding#

Bring your own bindings for the extension.

Exec#

Build an executable instead of an extension.

class setuptools_rust.Strip(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Enumeration of modes for stripping symbols from the built extension.

No#

Do not strip symbols.

Debug#

Strip debug symbols.

All#

Strip all symbols.