//python/cc:py_extension.bzl

Rules for creating Python C extension modules.

This module provides py_extension for building Python C extension modules that can be imported by Python targets (py_binary, py_test, py_library). It manages dynamic linking, symbol exports (PyInit_*), platform-specific link flags, and target dependencies cleanly.

See the Python C API documentation for information on writing C extension modules.

Warning

Experimental API. This API is still under development and may change or be removed without notice.

Added in version 2.3.0.

py_extension(name, srcs=None, hdrs=None, copts=None, defines=None, local_defines=None, includes=None, linkopts=None, deps=None, dynamic_deps=None, exports_filter=None, user_link_flags=None, additional_linker_inputs=None, module_name=None, py_limited_api=None, **kwargs)

Creates a Python extension module.

Warning

Experimental API. This API is still under development and may change or be removed without notice.

By default, extensions are created within their workspace package directory (e.g., pkg/ext.so) and imported using standard Python package paths (e.g., from pkg import ext).

To customize import path behavior:

• imports: Pass imports = ["..."] to append custom search directories to sys.path (matching py_library.imports).

• module_name: Pass module_name = "custom_name" to override the base module filename.

Added in version 2.3.0.

Args:

• name – (str)

  Target name.

• srcs – (list[Label | str] | None) (default None)

  C/C++ source files to compile directly for this extension.

• hdrs – (list[Label | str] | None) (default None)

  Header files for srcs.

• copts – (list[str] | None) (default None)

  Compiler flags for srcs.

• defines – (list[str] | None) (default None)

  Preprocessor defines for srcs.

• local_defines – (list[str] | None) (default None)

  Preprocessor defines for srcs passed to internal cc_library.

• includes – (list[str] | None) (default None)

  Header include search paths passed to internal cc_library.

• linkopts – (list[str] | None) (default None)

  Link options passed to internal cc_library created for srcs/hdrs. To pass linker flags to cc_shared_library, use user_link_flags.

• deps – (list[Label | str] | None) (default None)

  cc_library targets to statically link into the extension.

• dynamic_deps – (list[Label | str] | None) (default None)

  cc_shared_library targets to dynamically link.

• exports_filter – (list[str] | None) (default None)

  Filter for exported symbols passed to cc_shared_library.

• user_link_flags – (list[str] | None) (default None)

  Additional link flags passed to cc_shared_library. To pass linker flags that apply to srcs, use linkopts.

• additional_linker_inputs – (list[Label | str] | None) (default None)

  Additional linker inputs passed to cc_shared_library.

• module_name – (str | None) (default None)

  Custom Python module name. If not set, defaults to name.

• py_limited_api – (str | None) (default None)

  Python limited API version string (e.g., "3.8").

• kwargs – (dict)

  Additional arguments passed to the underlying wrapper rule.