feat(cc): introduce py_extension rule for C/C++ Python extension modules

python/cc/BUILD.bazel

@@ -79,3 +79,9 @@ alias(
     deprecation = "Use //python/cc:py_cc_toolchain_info instead",
     visibility = ["//visibility:public"],
 )
+
+bzl_library(
+    name = "py_extension",
+    srcs = ["py_extension.bzl"],
+    deps = ["//python/private/cc:py_extension_macro"],
+)

python/cc/py_extension.bzl

@@ -0,0 +1,12 @@
+"""Public API for py_extension.
+
+:::{include} /_includes/experimental_api.md
+:::
+"""
+
+load(
+    "//python/private/cc:py_extension_macro.bzl",
+    _py_extension = "py_extension",
+)
+
+py_extension = _py_extension

python/private/BUILD.bazel

@@ -506,6 +506,7 @@ bzl_library(
     deps = [
         ":py_cc_toolchain_rule",
         ":util",
+        "//python/private/pypi:pep508_env",
     ],
 )
 
@@ -514,6 +515,7 @@ bzl_library(
     srcs = ["py_cc_toolchain_rule.bzl"],
     deps = [
         ":common_labels",
+        ":flags",
         ":py_cc_toolchain_info",
         ":sentinel_impl",
         "@bazel_skylib//rules:common_settings",

python/private/cc/BUILD.bazel

@@ -1,3 +1,4 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load("@rules_cc//cc:cc_library.bzl", "cc_library")
 load("//python/private:visibility.bzl", "NOT_ACTUALLY_PUBLIC")
 
@@ -18,3 +19,68 @@ cc_library(
     name = "empty",
     visibility = NOT_ACTUALLY_PUBLIC,
 )
+
+# Private alias to avoid "duplicate dependency label" errors when users
+# explicitly pass //python/cc:current_py_cc_headers or //python/cc:current_py_cc_libs
+# in the deps attribute (including when deps is a select() expression).
+alias(
+    name = "current_py_cc_headers_private_alias",
+    actual = "//python/cc:current_py_cc_headers",
+    visibility = NOT_ACTUALLY_PUBLIC,
+)
+
+# Private alias to avoid "duplicate dependency label" errors when users
+# explicitly pass //python/cc:current_py_cc_headers or //python/cc:current_py_cc_libs
+# in the deps attribute (including when deps is a select() expression).
+alias(
+    name = "current_py_cc_libs_private_alias",
+    actual = "//python/cc:current_py_cc_libs",
+    visibility = NOT_ACTUALLY_PUBLIC,
+)
+
+bzl_library(
+    name = "py_extension_macro_bzl",
+    deps = [
+        ":py_extension_rule_bzl",
+        "//python/private:util",
+        "@rules_cc//cc:core_rules",
+    ],
+)
+
+bzl_library(
+    name = "py_extension_rule_bzl",
+    deps = [
+        "//python/private:attr_builders",
+        "//python/private:attributes",
+        "//python/private:py_info",
+        "//python/private:rule_builders",
+        "//python/private:toolchain_types",
+        "@rules_cc//cc/common",
+    ],
+)
+
+bzl_library(
+    name = "py_extension_macro",
+    srcs = ["py_extension_macro.bzl"],
+    deps = [
+        ":py_extension_rule",
+        "//python/private:util",
+        "@rules_cc//cc:core_rules",
+    ],
+)
+
+bzl_library(
+    name = "py_extension_rule",
+    srcs = ["py_extension_rule.bzl"],
+    deps = [
+        "//python/private:attr_builders",
+        "//python/private:attributes",
+        "//python/private:builders",
+        "//python/private:py_info",
+        "//python/private:reexports",
+        "//python/private:rule_builders",
+        "//python/private:toolchain_types",
+        "@bazel_skylib//lib:dicts",
+        "@rules_cc//cc/common",
+    ],
+)

python/private/cc/py_extension_macro.bzl

@@ -0,0 +1,186 @@
+"""Macro for creating Python extensions.
+
+:::{include} /_includes/experimental_api.md
+:::
+"""
+
+load("@rules_cc//cc:cc_library.bzl", "cc_library")
+load("@rules_cc//cc:cc_shared_library.bzl", "cc_shared_library")
+load("//python/private:util.bzl", "add_tag", "copy_propagating_kwargs")
+load(":py_extension_rule.bzl", "py_extension_wrapper")
+
+def py_extension(
+        name,
+        srcs = None,
+        hdrs = None,
+        copts = None,
+        defines = None,
+        includes = None,
+        linkopts = None,
+        linkshared = None,
+        linkstatic = None,
+        deps = None,
+        dynamic_deps = None,
+        exports_filter = None,
+        user_link_flags = None,
+        visibility = None,
+        data = None,
+        **kwargs):
+    """Creates a Python extension module.
+
+    :::{include} /_includes/experimental_api.md
+    :::
+
+    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 {attr}`py_library.imports`).
+    - `module_name`: Pass `module_name = "custom_name"` to override the base
+      module filename.
+
+    Args:
+        name: {type}`str` Target name.
+        srcs: {type}`list[Label | str] | None` C/C++ source files to compile
+            directly for this extension.
+        hdrs: {type}`list[Label | str] | None` Header files for `srcs`.
+        copts: {type}`list[str] | None` Compiler flags for `srcs`.
+        defines: {type}`list[str] | None` Preprocessor defines for `srcs`.
+        includes: {type}`list[str] | None` Header include search paths passed
+            to internal `cc_library`.
+        linkopts: {type}`list[str] | None` Link options passed to internal
+            `cc_library` and `cc_shared_library`.
+        linkshared: {type}`bool | None` Deprecated and ignored. Extensions are
+            always linked dynamically.
+        linkstatic: {type}`bool | None` The `linkstatic` flag passed to
+            internal `cc_library`.
+        deps: {type}`list[Label | str] | None` `cc_library` targets to
+            statically link into the extension.
+        dynamic_deps: {type}`list[Label | str] | None` `cc_shared_library`
+            targets to dynamically link.
+        exports_filter: {type}`list[str] | None` Filter for exported symbols
+            passed to `cc_shared_library`.
+        user_link_flags: {type}`list[str] | None` Additional link flags passed
+            to `cc_shared_library`.
+        visibility: {type}`list[Label | str] | None` Target visibility.
+        data: {type}`list[Label | str] | None` List of files or targets needed
+            by this extension at runtime.
+        **kwargs: {type}`dict` Additional arguments passed to the underlying
+            wrapper rule.
+    """
+    add_tag(kwargs, "@rules_python//python/cc:py_extension")
+    _ = linkshared  # buildifier: disable=unused-variable
+
+    csl_deps = []
+
+    copts = (copts or []) + [
+        # -fPIC (Position Independent Code) is required when compiling C/C++ sources into
+        # dynamic/shared libraries (.so/.dylib/.pyd) so code can be loaded at arbitrary addresses.
+        "-fPIC",
+    ]
+
+    # Private alias targets are appended to avoid "duplicate dependency label" errors
+    # if a user explicitly passes //python/cc:current_py_cc_headers or //python/cc:current_py_cc_libs
+    # in their deps attribute (including when deps is a select() expression).
+    py_cc_headers_and_win_libs = [
+        "//python/private/cc:current_py_cc_headers_private_alias",
+    ] + select({
+        "@platforms//os:windows": ["//python/private/cc:current_py_cc_libs_private_alias"],
+        "//conditions:default": [],
+    })
+    deps = (deps or []) + py_cc_headers_and_win_libs
+
+    # 1. If srcs or hdrs are specified, create an implicit cc_library for them
+    if srcs or hdrs:
+        impl_lib_name = "_" + name + "_impl"
+        impl_lib_kwargs = copy_propagating_kwargs(kwargs)
+        if includes:
+            impl_lib_kwargs["includes"] = includes
+        if linkopts:
+            impl_lib_kwargs["linkopts"] = linkopts
+        if linkstatic != None:
+            impl_lib_kwargs["linkstatic"] = linkstatic
+        cc_library(
+            name = impl_lib_name,
+            srcs = srcs,
+            hdrs = hdrs,
+            copts = copts,
+            defines = defines,
+            deps = deps,
+            visibility = ["//visibility:private"],
+            **impl_lib_kwargs
+        )
+        csl_deps.append(":" + impl_lib_name)
+
+    if csl_deps:
+        final_csl_deps = csl_deps
+    elif deps:
+        final_csl_deps = deps
+    else:
+        # cc_shared_library requires a dependency, so use an empty library when none are given.
+        final_csl_deps = ["//python/private/cc:empty"]
+
+    # 4. Create the underlying cc_shared_library
+    csl_name = "_" + name + "_csl"
+    csl_kwargs = copy_propagating_kwargs(kwargs)
+
+    # exports_filter specifies which target dependencies should have their exported
+    # symbols exposed by cc_shared_library. On Windows MSVC, cc_shared_library uses
+    # exports_filter to inspect the .obj files of matching targets and generate a .def
+    # file containing all __declspec(dllexport) symbols (such as PyInit_<name>).
+    # Defaulting to final_csl_deps ensures only the targets in this extension (e.g. _impl)
+    # are inspected, rather than all targets in the package. Note: current_py_cc_libs
+    # provides an import library (.lib), not object files (.obj), so MSVC link.exe
+    # does not re-export CPython runtime symbols.
+    csl_kwargs["exports_filter"] = exports_filter if exports_filter != None else final_csl_deps
+
+    effective_user_link_flags = (user_link_flags or linkopts or []) + select({
+        # On macOS, Apple's ld64 linker requires '-undefined dynamic_lookup' so CPython
+        # C-API symbols (e.g. PyModule_Create) remain unresolved at link time and are
+        # dynamically resolved at runtime when CPython loads the shared library (.so).
+        "@platforms//os:macos": ["-undefined", "dynamic_lookup"],
+        # On Windows, link.exe receives the CPython import library (.lib) passed via
+        # current_py_cc_libs.
+        "@platforms//os:windows": ["$(locations @rules_python//python/cc:current_py_cc_libs)"],
+        "//conditions:default": [],
+    })
+    csl_kwargs["user_link_flags"] = effective_user_link_flags
+
+    csl_additional_linker_inputs = select({
+        "@platforms//os:windows": ["@rules_python//python/cc:current_py_cc_libs"],
+        "//conditions:default": [],
+    })
+
+    cc_shared_library(
+        name = csl_name,
+        deps = final_csl_deps,
+        additional_linker_inputs = csl_additional_linker_inputs,
+        dynamic_deps = dynamic_deps,
+        visibility = ["//visibility:private"],
+        **csl_kwargs
+    )
+
+    # 5. Select default libc constraint if not provided
+    if "libc" not in kwargs:
+        kwargs["libc"] = select({
+            "@rules_python//python/config_settings:_is_py_linux_libc_glibc": "glibc",
+            "@rules_python//python/config_settings:_is_py_linux_libc_musl": "musl",
+            "//conditions:default": "glibc",
+        })
+
+    if data != None:
+        kwargs["data"] = data
+
+    # 6. Filter out C++ specific compilation/linking attributes before invoking wrapper rule
+    for cc_attr in ("includes", "linkopts", "linkshared", "linkstatic", "features"):
+        kwargs.pop(cc_attr, None)
+
+    # 7. Wrap with py_extension_wrapper for PEP 3149 naming & PyInfo
+    py_extension_wrapper(
+        name = name,
+        src = ":" + csl_name,
+        visibility = visibility,
+        **kwargs
+    )