feat: make conda-pypi mappings configurable

[tdejager]

Description

This PR makes the conda↔PyPI name mapping configurable in both directions:

• workspace conda-pypi-map now supports per-channel overlay/replacement mappings, inline entries, URL/file locations, hard disables, and an explicit same-name heuristic
• pixi-build-python now supports pypi-conda-map overrides before the PyPI→conda mapping service

The forward and reverse mappings intentionally have different shapes:

• conda-pypi-map is per channel and maps conda package names → one or more PyPI names because it decides which installed conda packages satisfy PyPI requirements/PURLs.
• pypi-conda-map is a flat map of PyPI package name → one conda package name or false because the build backend converts each Python requirement into at most one conda recipe dependency.

Example:

[workspace.conda-pypi-map]
# Additive overlay: project entries win, misses use Pixi's default mapping data.
conda-forge = { mapping = { pytorch = "torch", not-on-pypi = false } }

# Replace Pixi's default mapping data for this channel. Same-name guessing is separate.
my-company = { location = "https://internal.example.com/map.json", mapping-mode = "replace" }

# Hard-disable PyPI name derivation for this channel.
internal = false

[package.build.config]            # pixi-build-python
ignore-pypi-mapping = false
pypi-conda-map = { torch = "pytorch", my-internal-pkg = false }

Common configurations:

# Fix a few names, otherwise let Pixi do its best.
[workspace.conda-pypi-map]
conda-forge = { mapping = { pytorch = "torch", not-on-pypi = false } }

# Avoid default mapping lookups while keeping the conda-forge same-name heuristic.
# This is the explicit replacement for the deprecated `conda-pypi-map = {}`.
[workspace]
conda-pypi-map = { conda-forge = { mapping-mode = "replace" } }

# Treat a mapping file as the source of truth: no default mapping data and no same-name guesses.
[workspace.conda-pypi-map]
conda-forge = {
  location = "mapping.json",
  mapping-mode = "replace",
  same-name-heuristic = false,
}

# Enable the same-name heuristic for a non-conda-forge/private channel.
[workspace.conda-pypi-map]
my-internal = { mapping-mode = "replace", same-name-heuristic = true }

Concretely this PR:

1. Adds table entries for conda-pypi-map channels with:

   • location
   • inline mapping
   • mapping-mode = "overlay" | "replace"
   • same-name-heuristic = true | false

2. Keeps bare string entries as shorthand for an additive overlay location.

3. Supports multiple PyPI names for one conda package (airflow = ["airflow", "apache-airflow"]).

4. Makes false consistent at its scope:

   • conda-pypi-map = false disables all PyPI name derivation globally
   • <channel> = false disables all PyPI name derivation for that channel
   • mapping.package = false means that package is explicitly not on PyPI

5. Makes the same-name heuristic explicit:

   • default enabled for conda-forge
   • default disabled for other channels
   • can be enabled for any configured channel

6. Preserves the legacy behavior of conda-pypi-map = {} as a soft-deprecated spelling for “avoid default mapping lookups but keep conda-forge same-name guessing”. The explicit replacement is:

   [workspace]
   conda-pypi-map = { conda-forge = { mapping-mode = "replace" } }

7. Caches URL mapping locations via standard HTTP cache semantics: remote fetches go through the existing http-cache middleware (CacheMode::Default), which honors the server's Cache-Control/ETag. A freshly fetched mapping is reused on later solves without network access, a stale one is revalidated cheaply, and a previously fetched copy is reused when a refresh fails (unless the server marked the response no-store/must-revalidate) so offline solves keep working. No bespoke per-entry TTL knob is needed.

8. Adds pypi-conda-map to pixi-build-python, including target-specific per-key merge behavior.

9. Improves diagnostics for offline/firewalled mapping failures and HTML/GitHub-blob mapping URLs.

10. Cleans up pypi_mapping::resolvers naming (PrefixHash, PrefixCompressed, ProjectDefined, SameName).

Behavior changes

Existing manifest	Before	After	To get the old behavior
conda-forge = "mapping.json"	Exclusive: only packages in the file got PURLs.	Additive overlay: project entries win, misses use Pixi's default mapping data and then same-name if enabled.	conda-forge = { location = "mapping.json", mapping-mode = "replace", same-name-heuristic = false }
A mapping for channel A, while also using channel B	Configuring any project mapping suppressed the conda-forge same-name heuristic globally.	Channel B behaves as if no mapping were configured.	Configure B explicitly, e.g. B = false to disable it.
conda-pypi-map = {}	Avoided default mapping lookups while still allowing conda-forge same-name guessing.	Same behavior, but deprecated with a warning.	conda-pypi-map = { conda-forge = { mapping-mode = "replace" } }
conda-pypi-map = false	Disabled project/default lookups but still allowed conda-forge same-name guessing.	Hard-disable: no PyPI name derivation at all.	Use { conda-forge = { mapping-mode = "replace" } } if you only wanted no network/default lookups.

How Has This Been Tested?

Automated/unit/integration coverage includes:

• manifest parsing and snapshot diagnostics for the new mapping-mode, same-name-heuristic, false/null/list mapping values, and empty-map deprecation
• project mapping conversion and duplicate-channel validation
• overlay/replacement mapping behavior
• explicit package false preventing fallback
• channel/global hard-disable behavior
• legacy conda-pypi-map = {} behavior
• same-name heuristic defaulting to conda-forge and explicit enablement for another channel
• remote mapping caching: a second, independent solve reuses the on-disk HTTP cache without any network access, and an uncached remote mapping whose fetch fails is a hard error
• HTML/GitHub-blob parse hint
• pypi-conda-map override/skip/marker/merge behavior

Commands run locally:

cargo test -p pypi_mapping
cargo test -p pixi_manifest conda_pypi_map
cargo test -p pixi_core conda_pypi_map
cargo test -p pixi --test integration_rust conda_pypi_map_tests

Schema files were regenerated from schema/model.py and validated with pixi run -e schema test-schema.

AI Disclosure

• This PR contains AI-generated content.
  • I have tested AI-generated content in my PR.
  • I take responsibility for any AI-generated content in my PR.

Tools: Claude Code / pi coding agent

Checklist

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have added sufficient tests to cover my changes
• I have verified that changes that impact the JSON schema have been made in schema/model.py

[ruben-arts]

What is the reason for the addition of the cache-ttl on the remote mapping?

[ruben-arts]

I've done some user testing and it all seems to work as designed. I've got one question about the conda-pypi-map = false. I was expecting no mapping at all, e.g. if there is a pypi and conda map it's just going to get both packages.

I believe there is currently no way accept making an empty map and assigning that as replace. Was this behavior already existing?

[nichmor]

What is the reason for the addition of the cache-ttl on the remote mapping?

We want to cache the requested mapping and don't fetch it multiple times during the solve - for this reason, we thought that it would be great to allow users to choose how "fresh" the mapping should be for them, so we added this conf option

[tdejager]

What is the reason for the addition of the cache-ttl on the remote mapping?

We want to cache the requested mapping and don't fetch it multiple times during the solve - for this reason, we thought that it would be great to allow users to choose how "fresh" the mapping should be for them, so we added this conf option

@ruben-arts for reference the compressed mapping for conda-forge on GitHub which you might use is about 1MB :)