API Reference

class setuptools_rust.RustExtension(target, path='Cargo.toml', args=None, features=None, rustc_flags=None, 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 corresponds to compiled rust binaries and values are full name of the executable inside python package.

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

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

  • features (Optional[List[str]]) – A list of Cargo features to also build.

  • 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.

  • script (bool) – Generate console script for executable if Binding.Exec is used.

  • native (bool) – Build extension or executable with --target-cpu=native.

  • 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 (Union[bool, Literal[‘auto’]]) –

    Similar to py_limited_api on setuptools.Extension, this controls whether the built extension should be considered compatible with the PEP 384 “limited API”.

    • 'auto': the --py-limited-api option of setup.py bdist_wheel will control whether the extension is built as a limited api extension. The corresponding pyo3/abi3-pyXY feature will be set accordingly. This is the recommended setting, as it allows python setup.py install to build a version-specific extension for best performance.

    • True: the extension is assumed to be compatible with the limited abi. You must ensure this is the case (e.g. by setting the pyo3/abi3 feature).

    • False: the extension is version-specific.

class setuptools_rust.Binding(value)

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)

Enumeration of modes for stripping symbols from the built extension.

No

Do not strip symbols.

Debug

Strip debug symbols.

All

Strip all symbols.