Respect metadata_directory in build_wheel per PEP 517

When a PEP 517 frontend passes metadata_directory to build_wheel,
the built wheel should use the pre-generated metadata from that directory.
This enables wrapping build backends that modify metadata in
prepare_metadata_for_build_wheel.

Python side: when metadata_directory is not None, set
MATURIN_PEP517_METADATA_DIR in the subprocess environment.

Rust side: write_dist_info() checks the env var and copies files from
the pre-existing .dist-info directory instead of regenerating them.
The WHEEL file is always regenerated to ensure correct tags, and
RECORD is skipped since it is generated by WheelWriter::finish().
If the env var is set but the expected directory does not exist,
an error is raised instead of silently falling back.

Fixes #1973

Author: messense

maturin/__init__.py

@@ -108,9 +108,15 @@ def _build_wheel(
 
     command = [*base_command, *options]
 
+    env = _get_env()
+    if metadata_directory is not None:
+        if env is None:
+            env = os.environ.copy()
+        env["MATURIN_PEP517_METADATA_DIR"] = metadata_directory
+
     print("Running `{}`".format(" ".join(command)))
     sys.stdout.flush()
-    result = subprocess.run(command, stdout=subprocess.PIPE, env=_get_env())
+    result = subprocess.run(command, stdout=subprocess.PIPE, env=env)
     sys.stdout.buffer.write(result.stdout)
     sys.stdout.flush()
     if result.returncode != 0:

src/module_writer/mock_writer.rs

@@ -149,6 +149,7 @@ fn write_dist_info_uses_license_file_sources() -> Result<()> {
 }
 
 #[test]
+#[serial_test::serial]
 fn write_dist_info_rejects_absolute_license_paths() {
     use pep440_rs::Version;
     use std::str::FromStr;
@@ -173,3 +174,136 @@ fn write_dist_info_rejects_absolute_license_paths() {
         "unexpected error: {err:#}"
     );
 }
+
+#[test]
+#[serial_test::serial]
+fn write_dist_info_respects_metadata_directory_env_var() -> Result<()> {
+    use pep440_rs::Version;
+    use std::str::FromStr;
+
+    let temp_dir = tempfile::tempdir()?;
+    let pyproject_dir = temp_dir.path().join("crate");
+    fs_err::create_dir_all(&pyproject_dir)?;
+
+    let metadata = Metadata24::new("test-pkg".to_string(), Version::from_str("1.0.0").unwrap());
+    let dist_info_name = "test_pkg-1.0.0.dist-info";
+
+    // Create a pre-generated .dist-info directory with custom METADATA
+    let metadata_dir = temp_dir.path().join("metadata");
+    let pre_existing_dir = metadata_dir.join(dist_info_name);
+    fs_err::create_dir_all(&pre_existing_dir)?;
+
+    let custom_metadata =
+        "Metadata-Version: 2.4\nName: test-pkg\nVersion: 1.0.0\nClassifier: Custom :: Classifier\n";
+    fs_err::write(pre_existing_dir.join("METADATA"), custom_metadata)?;
+    fs_err::write(pre_existing_dir.join("WHEEL"), "should be overwritten")?;
+    fs_err::write(pre_existing_dir.join("RECORD"), "should be skipped")?;
+    fs_err::write(
+        pre_existing_dir.join("entry_points.txt"),
+        "[console_scripts]\nfoo=bar:main\n",
+    )?;
+
+    // Create a licenses/ subdirectory
+    let licenses_dir = pre_existing_dir.join("licenses");
+    fs_err::create_dir_all(&licenses_dir)?;
+    fs_err::write(licenses_dir.join("LICENSE"), "MIT License")?;
+
+    // Per PEP 517, metadata_directory points to the .dist-info directory itself
+    // SAFETY: This test is serialized and the env var is removed before returning.
+    unsafe { std::env::set_var("MATURIN_PEP517_METADATA_DIR", &pre_existing_dir) };
+    let mut writer = VirtualWriter::new(MockWriter::default(), Override::empty());
+    let tags = &["cp310-cp310-manylinux_2_17_x86_64".to_string()];
+    let result = write_dist_info(&mut writer, &pyproject_dir, &metadata, tags);
+    unsafe { std::env::remove_var("MATURIN_PEP517_METADATA_DIR") };
+    result?;
+
+    let files = writer.finish()?;
+
+    // METADATA should be the custom one, not regenerated
+    let metadata_key = Path::new(dist_info_name).join("METADATA");
+    assert_eq!(
+        str::from_utf8(&files[&metadata_key]).unwrap(),
+        custom_metadata
+    );
+
+    // WHEEL should be regenerated with correct tags, not the pre-existing content
+    let wheel_key = Path::new(dist_info_name).join("WHEEL");
+    let wheel_content = str::from_utf8(&files[&wheel_key]).unwrap();
+    assert!(
+        wheel_content.contains("Tag: cp310-cp310-manylinux_2_17_x86_64"),
+        "WHEEL should contain the correct tag, got: {wheel_content}"
+    );
+    assert!(
+        !wheel_content.contains("should be overwritten"),
+        "WHEEL should be regenerated, not copied"
+    );
+
+    // RECORD should not be present (it's generated later by WheelWriter)
+    let record_key = Path::new(dist_info_name).join("RECORD");
+    assert!(!files.contains_key(&record_key));
+
+    // entry_points.txt should be copied
+    let ep_key = Path::new(dist_info_name).join("entry_points.txt");
+    assert_eq!(
+        str::from_utf8(&files[&ep_key]).unwrap(),
+        "[console_scripts]\nfoo=bar:main\n"
+    );
+
+    // License file from subdirectory should be copied
+    let license_key = Path::new(dist_info_name).join("licenses").join("LICENSE");
+    assert_eq!(str::from_utf8(&files[&license_key]).unwrap(), "MIT License");
+
+    Ok(())
+}
+
+#[test]
+#[serial_test::serial]
+fn write_dist_info_metadata_dir_as_parent_directory() -> Result<()> {
+    use pep440_rs::Version;
+    use std::str::FromStr;
+
+    let temp_dir = tempfile::tempdir()?;
+    let pyproject_dir = temp_dir.path().join("crate");
+    fs_err::create_dir_all(&pyproject_dir)?;
+
+    let metadata = Metadata24::new("test-pkg".to_string(), Version::from_str("1.0.0").unwrap());
+    let dist_info_name = "test_pkg-1.0.0.dist-info";
+
+    // Create a parent directory containing the .dist-info subdirectory
+    let parent_dir = temp_dir.path().join("metadata");
+    let pre_existing_dir = parent_dir.join(dist_info_name);
+    fs_err::create_dir_all(&pre_existing_dir)?;
+
+    let custom_metadata =
+        "Metadata-Version: 2.4\nName: test-pkg\nVersion: 1.0.0\nClassifier: Custom :: Classifier\n";
+    fs_err::write(pre_existing_dir.join("METADATA"), custom_metadata)?;
+    fs_err::write(pre_existing_dir.join("WHEEL"), "should be overwritten")?;
+
+    // Set env var to the parent directory (PEP 517 spec form)
+    // SAFETY: This test is serialized and the env var is removed before returning.
+    unsafe { std::env::set_var("MATURIN_PEP517_METADATA_DIR", &parent_dir) };
+    let mut writer = VirtualWriter::new(MockWriter::default(), Override::empty());
+    let tags = &["cp310-cp310-manylinux_2_17_x86_64".to_string()];
+    let result = write_dist_info(&mut writer, &pyproject_dir, &metadata, tags);
+    unsafe { std::env::remove_var("MATURIN_PEP517_METADATA_DIR") };
+    result?;
+
+    let files = writer.finish()?;
+
+    // METADATA should be the custom one
+    let metadata_key = Path::new(dist_info_name).join("METADATA");
+    assert_eq!(
+        str::from_utf8(&files[&metadata_key]).unwrap(),
+        custom_metadata
+    );
+
+    // WHEEL should be regenerated
+    let wheel_key = Path::new(dist_info_name).join("WHEEL");
+    let wheel_content = str::from_utf8(&files[&wheel_key]).unwrap();
+    assert!(
+        wheel_content.contains("Tag: cp310-cp310-manylinux_2_17_x86_64"),
+        "WHEEL should contain the correct tag, got: {wheel_content}"
+    );
+
+    Ok(())
+}

src/module_writer/mod.rs

@@ -289,7 +289,12 @@ fn add_data_subdir(
     Ok(())
 }
 
-/// Creates the .dist-info directory and fills it with all metadata files except RECORD
+/// Creates the .dist-info directory and fills it with all metadata files except RECORD.
+///
+/// If the `MATURIN_PEP517_METADATA_DIR` environment variable is set, copies the
+/// pre-generated metadata files from that directory instead of regenerating them.
+/// The WHEEL file is always regenerated to ensure correct tags. This implements
+/// the PEP 517 requirement that `build_wheel` respects `metadata_directory`.
 pub fn write_dist_info(
     writer: &mut VirtualWriter<impl ModuleWriterInternal>,
     pyproject_dir: &Path,
@@ -298,6 +303,38 @@ pub fn write_dist_info(
 ) -> Result<PathBuf> {
     let dist_info_dir = metadata24.get_dist_info_dir();
 
+    if let Ok(metadata_dir) = std::env::var("MATURIN_PEP517_METADATA_DIR") {
+        let metadata_path = Path::new(&metadata_dir);
+        // Support both forms:
+        //   1. Direct .dist-info path (pip's behavior)
+        //   2. Parent directory containing the .dist-info subdirectory (per PEP 517 spec)
+        let pre_existing = if metadata_path.is_dir()
+            && metadata_path
+                .file_name()
+                .is_some_and(|n| n.to_string_lossy().ends_with(".dist-info"))
+        {
+            metadata_path.to_path_buf()
+        } else {
+            let nested = metadata_path.join(&dist_info_dir);
+            if nested.is_dir() {
+                nested
+            } else {
+                bail!(
+                    "MATURIN_PEP517_METADATA_DIR is set to '{}' but no .dist-info directory \
+                     was found (tried both '{}' directly and '{}')",
+                    metadata_dir,
+                    metadata_path.display(),
+                    metadata_path.join(&dist_info_dir).display(),
+                );
+            }
+        };
+        debug!(
+            "Using pre-generated metadata from {}",
+            pre_existing.display()
+        );
+        return write_dist_info_from_dir(writer, &dist_info_dir, &pre_existing, tags);
+    }
+
     writer.add_bytes(
         dist_info_dir.join("METADATA"),
         None,
@@ -362,6 +399,57 @@ pub fn write_dist_info(
     Ok(dist_info_dir)
 }
 
+/// Copies pre-generated metadata files from a `.dist-info` directory on disk into the wheel,
+/// but always regenerates the WHEEL file to ensure correct tags.
+fn write_dist_info_from_dir(
+    writer: &mut VirtualWriter<impl ModuleWriterInternal>,
+    dist_info_dir: &Path,
+    source_dir: &Path,
+    tags: &[String],
+) -> Result<PathBuf> {
+    // Always regenerate WHEEL to ensure correct tags for the built wheel
+    writer.add_bytes(
+        dist_info_dir.join("WHEEL"),
+        None,
+        wheel_file(tags)?.as_bytes(),
+        false,
+    )?;
+
+    // Copy all other files from the pre-generated .dist-info directory
+    for entry in fs::read_dir(source_dir)? {
+        let entry = entry?;
+        let file_name = entry.file_name();
+        let file_name_str = file_name.to_string_lossy();
+
+        // Skip WHEEL (already regenerated) and RECORD (will be regenerated by WheelWriter)
+        if file_name_str == "WHEEL" || file_name_str == "RECORD" {
+            continue;
+        }
+
+        let entry_path = entry.path();
+        if entry_path.is_dir() {
+            // Recursively add subdirectories (e.g. licenses/)
+            for sub_entry in walkdir::WalkDir::new(&entry_path) {
+                let sub_entry = sub_entry?;
+                if sub_entry.file_type().is_file() {
+                    let rel = sub_entry.path().strip_prefix(source_dir).with_context(|| {
+                        format!(
+                            "walkdir entry '{}' is not under source dir '{}'",
+                            sub_entry.path().display(),
+                            source_dir.display()
+                        )
+                    })?;
+                    writer.add_file(dist_info_dir.join(rel), sub_entry.path(), false)?;
+                }
+            }
+        } else {
+            writer.add_file(dist_info_dir.join(&file_name), &entry_path, false)?;
+        }
+    }
+
+    Ok(dist_info_dir.to_owned())
+}
+
 /// Add a pth file to wheel root for editable installs
 pub fn write_pth(
     writer: &mut VirtualWriter<WheelWriter>,