python-dep-conflict-resolution

Answer

The core insight: when pip show <parent> lists a dependency as Requires: pydantic-core==2.46.4, that's an exact-version pin. Upgrading that dependency independently will break the parent at import time. The fix is a pre-upgrade check that inspects Requires fields of all installed packages before allowing a dependency upgrade.

Here's a reusable Python function and CLI tool:

"""
dependency-conflict-checker.py — Detect exact-version pins before upgrading.

Usage:
    python dependency-conflict-checker.py pydantic-core 2.47.0
    python dependency-conflict-checker.py --all  # check all installed pkgs
"""

import subprocess
import sys
import json
import re
from collections import defaultdict
from packaging.specifiers import SpecifierSet
from packaging.version import Version


def get_pip_show(package: str) -> dict | None:
    """Run `pip show <package>` and return structured info, or None."""
    try:
        result = subprocess.run(
            ["pip", "show", package],
            capture_output=True, text=True, check=True,
        )
    except subprocess.CalledProcessError:
        return None

    info = {}
    for line in result.stdout.strip().splitlines():
        if ": " in line:
            key, val = line.split(": ", 1)
            info[key.strip()] = val.strip()
    return info


def parse_requires(requires_str: str | None) -> list[dict]:
    """
    Parse the 'Requires:' field from pip show into structured entries.

    Example input:  "pydantic-core==2.46.4, typing-extensions>=4.6.1"
    Returns:        [{"name":"pydantic-core","specifier":"==2.46.4","exact":True}, ...]
    """
    if not requires_str:
        return []

    entries = []
    # Split on comma — but be careful of version specifiers containing commas
    parts = [p.strip() for p in requires_str.replace("\n", "").split(",") if p.strip()]

    for part in parts:
        # Match package name + optional specifiers like >=, ==, ~=, !=, >, <
        # Package names can have [extra] syntax e.g., "pydantic[email]>=2.0"
        m = re.match(
            r"^([a-zA-Z0-9][\w.-]*(?:\[[\w,\s]+\])?)\s*"  # name with optional extras
            r"([><=!~]+\s*[\w.*]+(?:\s*,\s*[><=!~]+\s*[\w.*]+)*)?\s*$",
            part,
        )
        if m:
            name = m.group(1).split("[")[0]  # strip extras bracket
            spec = m.group(2) or ""
            spec_clean = spec.strip()
            entries.append({
                "name": name,
                "specifier_raw": spec_clean,
                "exact": spec_clean.startswith("==") and "," not in spec_clean,
                "specifier_set": SpecifierSet(spec_clean) if spec_clean else None,
            })
    return entries


def find_pinning_parents(target_dep: str) -> list[dict]:
    """
    Find all installed packages that pin *target_dep* with an exact (==) version.

    Returns a list of dicts:
        [{"parent":"pydantic","version":"2.13.4","pinned_version":"2.46.4"}, ...]
    """
    parents = []
    result = subprocess.run(
        ["pip", "list", "--format=columns", "--disable-pip-version-check"],
        capture_output=True, text=True, check=True,
    )
    for line in result.stdout.strip().splitlines()[2:]:  # skip headers
        parts = line.split()
        if not parts:
            continue
        pkg_name = parts[0]
        pkg_version = parts[1] if len(parts) > 1 else "?"
        info = get_pip_show(pkg_name)
        if not info:
            continue
        reqs = parse_requires(info.get("Requires", ""))
        for req in reqs:
            if req["name"].lower() == target_dep.lower() and req["exact"]:
                parents.append({
                    "parent": pkg_name,
                    "parent_version": pkg_version,
                    "dependency": target_dep,
                    "pinned_version": req["specifier_raw"].lstrip("==").strip(),
                })
    return parents


def is_upgrade_safe(dependency: str, target_version: str) -> dict:
    """
    Check if upgrading *dependency* to *target_version* is safe.

    Returns:
    {
        "safe": True/False,
        "dependency": ...,
        "target_version": ...,
        "blocks": [list of blocking parents with pinned versions],
    }
    """
    parents = find_pinning_parents(dependency)
    blocks = []
    for p in parents:
        if Version(target_version) != Version(p["pinned_version"]):
            blocks.append(p)

    return {
        "safe": len(blocks) == 0,
        "dependency": dependency,
        "target_version": target_version,
        "blocks": blocks,
    }


def check_all_installed() -> list[dict]:
    """Run the check for every installed package to find all pinned deps."""
    result = subprocess.run(
        ["pip", "list", "--format=columns", "--disable-pip-version-check"],
        capture_output=True, text=True, check=True,
    )
    all_findings = []
    for line in result.stdout.strip().splitlines()[2:]:
        parts = line.split()
        if not parts:
            continue
        pkg = parts[0]
        info = get_pip_show(pkg)
        if not info:
            continue
        reqs = parse_requires(info.get("Requires", ""))
        for req in reqs:
            if req["exact"]:
                all_findings.append({
                    "parent": pkg,
                    "parent_version": parts[1] if len(parts) > 1 else "?",
                    "dependency": req["name"],
                    "pinned_version": req["specifier_raw"].lstrip("==").strip(),
                })
    return all_findings


# ---------------------------------------------------------------------------
# CLI entry point
# ---------------------------------------------------------------------------
if __name__ == "__main__":
    import argparse

    parser = argparse.ArgumentParser(
        description="Detect exact-version dependency pins before upgrading."
    )
    parser.add_argument("dependency", nargs="?", help="Dependency to check")
    parser.add_argument("target_version", nargs="?", help="Target version to upgrade to")
    parser.add_argument(
        "--all", action="store_true",
        help="Scan all installed packages for exact pins",
    )
    parser.add_argument(
        "--json", action="store_true",
        help="Output as JSON",
    )

    args = parser.parse_args()

    if args.all:
        findings = check_all_installed()
        if args.json:
            print(json.dumps(findings, indent=2))
        else:
            if not findings:
                print("✅ No exact-version pins found among installed packages.")
            else:
                print(f"⚠️  Found {len(findings)} exact-version pin(s):")
                for f in findings:
                    print(f"   {f['parent']}=={f['parent_version']} "
                          f"pins {f['dependency']}=={f['pinned_version']}")
        sys.exit(0 if not findings else 1)

    if not args.dependency or not args.target_version:
        parser.print_help()
        sys.exit(1)

    result = is_upgrade_safe(args.dependency, args.target_version)
    if args.json:
        print(json.dumps(result, indent=2))
    else:
        if result["safe"]:
            print(f"✅ Safe to upgrade {args.dependency} to {args.target_version}")
        else:
            print(f"❌ BLOCKED: upgrading {args.dependency} to {args.target_version}")
            for b in result["blocks"]:
                print(f"   → {b['parent']}=={b['parent_version']} "
                      f"requires {b['dependency']}=={b['pinned_version']}")
    sys.exit(0 if result["safe"] else 1)

How it works:

1. find_pinning_parents(dep) — scans every installed package via pip list → pip show and parses the Requires: field looking for package==exact_version patterns (no comma-separated multi-constraint — that indicates a range, not a pin).

2. is_upgrade_safe(dep, version) — calls find_pinning_parents, then checks if the target version matches the pinned version. If any parent pins a different exact version, the upgrade is blocked.

3. check_all_installed() — bulk scan to identify all exact pins in the environment, useful for auditing before a batch upgrade.

4. parse_requires() — robustly handles extras syntax (pydantic[email]>=2.0), multi-constraint specifiers (>=1.0,<2.0), and normalizes package names.

Standalone one-liner for quick shell checks:

# Check if pydantic-core is pinned before upgrading
pip show pydantic 2>/dev/null \
  | grep -i "requires:" \
  | grep -ioE "pydantic-core==[0-9.]+"

Integration into a pip upgrade wrapper (bash or Makefile):

# Makefile snippet
check-pin:
    python dependency-conflict-checker.py $(dep) $(ver) --json \
      | jq -e '.safe' > /dev/null \
      && echo "Proceeding..." \
      || (echo "Blocked by parent pins"; exit 1)

upgrade: check-pin
    pip install $(dep)==$(ver)