whl2conda.api.compare¶

@dataclass(slots=True)
class CompareOptions:
    """Options controlling conda package comparison."""

    strict: bool = False
    """Promote NOTICE differences to ERROR."""

    ignore: set[DiffCategory] = field(default_factory=set)
    """Categories demoted to EXPECTED severity."""

    extra_run_exports: set[str] = field(default_factory=set)
    """Additional dependency names treated as benign run-exports."""

    renames: dict[str, str] | None = None
    """pypi to conda package rename map.

    Defaults to the standard rename table from [load_std_renames][whl2conda.api.stdrename.].
    """

@dataclass(slots=True)
class ComparisonResult:
    """Result of comparing two conda packages."""

    package1: Path
    """First package (the package under test)."""

    package2: Path
    """Second package (the reference package)."""

    differences: list[Difference]
    """All differences found, including expected ones."""

    @property
    def errors(self) -> list[Difference]:
        """Differences with ERROR severity."""
        return [d for d in self.differences if d.severity >= Severity.ERROR]

    @property
    def ok(self) -> bool:
        """True if no ERROR severity differences were found."""
        return not self.errors

    def report(self, *, min_severity: Severity = Severity.NOTICE) -> str:
        """Generate a human readable report.

        Args:
            min_severity: only include differences of at least this severity.

        Returns:
            Multi-line report string.
        """
        lines = [f"Comparing {self.package1}", f"   against {self.package2}", ""]
        shown = [d for d in self.differences if d.severity >= min_severity]
        suppressed = len(self.differences) - len(shown)
        for d in sorted(shown, key=lambda d: (-d.severity, d.category.value, d.key)):
            lines.append(str(d))
            if d.left is not None:
                lines.append(f"    package1: {d.left}")
            if d.right is not None:
                lines.append(f"    package2: {d.right}")
        n_errors = len(self.errors)
        n_notices = sum(1 for d in self.differences if d.severity == Severity.NOTICE)
        lines.append("")
        summary = f"{n_errors} errors, {n_notices} notices"
        if suppressed:
            summary += f" ({suppressed} differences suppressed)"
        lines.append(summary)
        return "\n".join(lines)

    def to_json(self) -> dict[str, Any]:
        """JSON-compatible dictionary representation."""

        def _safe(val: Any) -> Any:
            if val is None or isinstance(val, (bool, int, float, str)):
                return val
            if isinstance(val, (list, tuple, set, frozenset)):
                return sorted(str(v) for v in val)
            return str(val)

        return {
            "package1": str(self.package1),
            "package2": str(self.package2),
            "ok": self.ok,
            "differences": [
                {
                    "category": d.category.value,
                    "severity": d.severity.name,
                    "key": d.key,
                    "description": d.description,
                    "left": _safe(d.left),
                    "right": _safe(d.right),
                }
                for d in self.differences
            ],
        }

class DiffCategory(enum.Enum):
    """Category of a difference between two conda packages."""

    # index.json / metadata
    PACKAGE_NAME = "package-name"
    PACKAGE_VERSION = "package-version"
    BUILD_STRING = "build-string"
    BUILD_NUMBER = "build-number"
    NOARCH_VS_PLATFORM = "noarch-vs-platform"
    LICENSE = "license"
    ABOUT_FIELD = "about-field"
    TIMESTAMP = "timestamp"
    # dependencies
    DEP_MISSING = "dep-missing"
    DEP_EXTRA = "dep-extra"
    DEP_RUN_EXPORT = "dep-run-export"
    DEP_VERSION = "dep-version"
    DEP_UNRENAMED = "dep-unrenamed"
    PYTHON_PIN = "python-pin"
    # files
    FILE_MISSING = "file-missing"
    FILE_EXTRA = "file-extra"
    FILE_CONTENT = "file-content"
    BINARY_CONTENT = "binary-content"
    PYCACHE = "pycache"
    ENTRY_POINT = "entry-point"
    # dist-info
    DIST_INFO_METADATA = "dist-info-metadata"
    DIST_INFO_OTHER = "dist-info-other"
    # info/ bookkeeping
    INFO_EXTRA_FILE = "info-extra-file"

    def __str__(self) -> str:
        return self.value

@dataclass(frozen=True, slots=True)
class Difference:
    """A single difference between two conda packages."""

    category: DiffCategory
    """Category of the difference."""

    severity: Severity
    """Severity of the difference."""

    key: str
    """Locus of the difference, e.g. `index.json:depends` or a file path."""

    description: str
    """Human readable one line description."""

    left: Any = None
    """Relevant value from the first package, if any."""

    right: Any = None
    """Relevant value from the second (reference) package, if any."""

    def __str__(self) -> str:
        return f"{self.severity.name} {self.category} {self.key}: {self.description}"

class Severity(enum.IntEnum):
    """Severity of a difference between two conda packages."""

    EXPECTED = 0
    """Benign difference inherent to the different build processes."""

    NOTICE = 1
    """Notable difference that is not necessarily a problem."""

    ERROR = 2
    """Unexpected difference that likely indicates a problem."""