pip-check-resolve 0.1.0__tar.gz

pip_check_resolve-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: pip-check-resolve
+Version: 0.1.0
+Summary: Explain installed Python dependency conflicts and their causal paths
+Project-URL: Homepage, https://github.com/matplo/pip-check-resolve
+Project-URL: Repository, https://github.com/matplo/pip-check-resolve
+Project-URL: Issues, https://github.com/matplo/pip-check-resolve/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: packaging>=24
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+
+# pip-check-resolve
+
+`pip-check-resolve` inspects an installed Python environment without changing it.
+It finds missing or incompatible dependencies and traces each problem back to the
+likely top-level packages that caused it.
+
+Unlike a resolver, it answers **why the environment that exists now is broken**.
+It does not install packages, try alternative versions, or contact PyPI.
+
+## Usage
+
+Run inside the environment to inspect the current interpreter:
+
+```console
+$ pip-check-resolve
+```
+
+Or keep the tool isolated and point it at another environment:
+
+```console
+$ uvx --from pip-check-resolve pip-check-resolve --python .venv/bin/python
+```
+
+Machine-readable output and expanded causal paths are available:
+
+```console
+$ pip-check-resolve --python .venv/bin/python --format json
+$ pip-check-resolve --all-paths --max-paths 100
+```
+
+Exit status is `0` for a consistent environment, `1` when package or metadata
+issues are found, and `2` when the target interpreter cannot be inspected.
+
+## What is checked
+
+- missing dependencies;
+- versions that do not satisfy their declared requirements;
+- incompatible `Requires-Python` metadata;
+- duplicate normalized distribution names;
+- malformed package requirements or metadata.
+
+Roots are identified from a distribution's `REQUESTED` marker when available and
+otherwise inferred from the installed dependency graph. Python packaging does not
+reliably preserve which extras were requested, so requirements conditional on
+`extra` are skipped and the report records that limitation.
+
+## Releasing
+
+Releases are published from GitHub tags using PyPI Trusted Publishing. The tag
+must be the project version prefixed with `v`, for example `v0.1.0`. Update the
+version in both `pyproject.toml` and `src/pip_check_resolve/__init__.py`, commit,
+and then create and push the matching tag:
+
+```console
+$ git tag v0.1.0
+$ git push origin v0.1.0
+```
+
+The `publish.yml` workflow tests the package, builds and checks its wheel and
+source distribution, and publishes them to PyPI using short-lived OIDC
+credentials. The PyPI Trusted Publisher must use owner `matplo`, repository
+`pip-check-resolve`, workflow `publish.yml`, and environment `pypi`.
+

pip_check_resolve-0.1.0/README.md

@@ -0,0 +1,63 @@
+# pip-check-resolve
+
+`pip-check-resolve` inspects an installed Python environment without changing it.
+It finds missing or incompatible dependencies and traces each problem back to the
+likely top-level packages that caused it.
+
+Unlike a resolver, it answers **why the environment that exists now is broken**.
+It does not install packages, try alternative versions, or contact PyPI.
+
+## Usage
+
+Run inside the environment to inspect the current interpreter:
+
+```console
+$ pip-check-resolve
+```
+
+Or keep the tool isolated and point it at another environment:
+
+```console
+$ uvx --from pip-check-resolve pip-check-resolve --python .venv/bin/python
+```
+
+Machine-readable output and expanded causal paths are available:
+
+```console
+$ pip-check-resolve --python .venv/bin/python --format json
+$ pip-check-resolve --all-paths --max-paths 100
+```
+
+Exit status is `0` for a consistent environment, `1` when package or metadata
+issues are found, and `2` when the target interpreter cannot be inspected.
+
+## What is checked
+
+- missing dependencies;
+- versions that do not satisfy their declared requirements;
+- incompatible `Requires-Python` metadata;
+- duplicate normalized distribution names;
+- malformed package requirements or metadata.
+
+Roots are identified from a distribution's `REQUESTED` marker when available and
+otherwise inferred from the installed dependency graph. Python packaging does not
+reliably preserve which extras were requested, so requirements conditional on
+`extra` are skipped and the report records that limitation.
+
+## Releasing
+
+Releases are published from GitHub tags using PyPI Trusted Publishing. The tag
+must be the project version prefixed with `v`, for example `v0.1.0`. Update the
+version in both `pyproject.toml` and `src/pip_check_resolve/__init__.py`, commit,
+and then create and push the matching tag:
+
+```console
+$ git tag v0.1.0
+$ git push origin v0.1.0
+```
+
+The `publish.yml` workflow tests the package, builds and checks its wheel and
+source distribution, and publishes them to PyPI using short-lived OIDC
+credentials. The PyPI Trusted Publisher must use owner `matplo`, repository
+`pip-check-resolve`, workflow `publish.yml`, and environment `pypi`.
+

pip_check_resolve-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pip-check-resolve"
+version = "0.1.0"
+description = "Explain installed Python dependency conflicts and their causal paths"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["packaging>=24"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: System :: Systems Administration",
+]
+
+[project.urls]
+Homepage = "https://github.com/matplo/pip-check-resolve"
+Repository = "https://github.com/matplo/pip-check-resolve"
+Issues = "https://github.com/matplo/pip-check-resolve/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.scripts]
+pip-check-resolve = "pip_check_resolve.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

pip_check_resolve-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pip_check_resolve-0.1.0/src/pip_check_resolve/__init__.py

@@ -0,0 +1,4 @@
+"""Explain dependency conflicts in installed Python environments."""
+
+__version__ = "0.1.0"
+

pip_check_resolve-0.1.0/src/pip_check_resolve/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+raise SystemExit(main())
+

pip_check_resolve-0.1.0/src/pip_check_resolve/analysis.py

@@ -0,0 +1,383 @@
+"""Analyze an installed-distribution snapshot as a dependency graph."""
+
+from __future__ import annotations
+
+from collections import defaultdict, deque
+from dataclasses import dataclass, field
+import re
+from typing import Any, Iterable
+
+from packaging.markers import default_environment
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.specifiers import InvalidSpecifier, SpecifierSet
+from packaging.utils import canonicalize_name
+from packaging.version import InvalidVersion, Version
+
+from .probe import Snapshot
+
+
+_EXTRA_MARKER = re.compile(
+    r"(?:^|[\s(])extra\s*(?:===|==|!=|~=|<=|>=|<|>|in\b|not\s+in\b)"
+    r"|(?:===|==|!=|~=|<=|>=|<|>|in\b|not\s+in\b)\s*extra(?:[\s)]|$)",
+    re.IGNORECASE,
+)
+
+
+@dataclass
+class Distribution:
+    name: str
+    key: str
+    version: str | None
+    requires_dist: list[str]
+    requires_python: str | None
+    requested: bool
+    metadata_location: str | None
+
+
+@dataclass
+class CausalPath:
+    packages: list[str]
+    root: str
+    root_attribution: str
+
+
+@dataclass
+class Issue:
+    code: str
+    package: str
+    message: str
+    requirement: str | None = None
+    dependency: str | None = None
+    installed_versions: list[str] = field(default_factory=list)
+    paths: list[CausalPath] = field(default_factory=list)
+    paths_truncated: bool = False
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Report:
+    target_python: str
+    environment: dict[str, str]
+    package_count: int
+    roots: dict[str, str]
+    issues: list[Issue]
+    warnings: list[str]
+
+    @property
+    def clean(self) -> bool:
+        return not self.issues
+
+
+def _marker_environment(snapshot: Snapshot) -> dict[str, str]:
+    environment = default_environment()
+    environment.update({key: str(value) for key, value in snapshot.environment.items()})
+    environment["extra"] = ""
+    return environment
+
+
+def _display_name(distributions: dict[str, list[Distribution]], key: str) -> str:
+    values = distributions.get(key)
+    return values[0].name if values else key
+
+
+def _shortest_paths(graph: dict[str, set[str]], root: str, target: str, limit: int) -> tuple[list[list[str]], bool]:
+    if root == target:
+        return [[root]], False
+
+    queue: deque[list[str]] = deque([[root]])
+    best_depth: dict[str, int] = {root: 0}
+    found: list[list[str]] = []
+    target_depth: int | None = None
+    truncated = False
+
+    while queue:
+        path = queue.popleft()
+        depth = len(path) - 1
+        if target_depth is not None and depth >= target_depth:
+            continue
+        for child in sorted(graph.get(path[-1], ())):
+            if child in path:
+                continue
+            next_depth = depth + 1
+            known = best_depth.get(child)
+            if known is not None and next_depth > known:
+                continue
+            best_depth[child] = next_depth
+            next_path = [*path, child]
+            if child == target:
+                target_depth = next_depth
+                if len(found) < limit:
+                    found.append(next_path)
+                else:
+                    truncated = True
+            else:
+                queue.append(next_path)
+    return found, truncated
+
+
+def _all_simple_paths(graph: dict[str, set[str]], root: str, target: str, limit: int) -> tuple[list[list[str]], bool]:
+    found: list[list[str]] = []
+    truncated = False
+
+    def visit(node: str, path: list[str]) -> None:
+        nonlocal truncated
+        if len(found) >= limit:
+            truncated = True
+            return
+        if node == target:
+            found.append(path.copy())
+            return
+        for child in sorted(graph.get(node, ())):
+            if child not in path:
+                visit(child, [*path, child])
+                if truncated:
+                    return
+
+    visit(root, [root])
+    return found, truncated
+
+
+def _attach_paths(
+    issues: Iterable[Issue],
+    graph: dict[str, set[str]],
+    roots: dict[str, str],
+    distributions: dict[str, list[Distribution]],
+    *,
+    all_paths: bool,
+    max_paths: int,
+) -> None:
+    path_finder = _all_simple_paths if all_paths else _shortest_paths
+    for issue in issues:
+        target = canonicalize_name(issue.package)
+        remaining = max_paths
+        attached: list[CausalPath] = []
+        truncated = False
+        for root in sorted(roots):
+            if remaining <= 0:
+                truncated = True
+                break
+            paths, root_truncated = path_finder(graph, root, target, remaining)
+            truncated = truncated or root_truncated
+            for path in paths:
+                names = [_display_name(distributions, key) for key in path]
+                attached.append(CausalPath(names, names[0], roots[root]))
+            remaining -= len(paths)
+
+        if not attached:
+            name = _display_name(distributions, target)
+            attached = [CausalPath([name], name, "unattributed")]
+        issue.paths = attached
+        issue.paths_truncated = truncated
+
+
+def analyze(snapshot: Snapshot, *, all_paths: bool = False, max_paths: int = 20) -> Report:
+    """Return dependency issues and causal paths for an environment snapshot."""
+
+    distributions: dict[str, list[Distribution]] = defaultdict(list)
+    issues: list[Issue] = []
+    warnings: list[str] = []
+
+    for index, record in enumerate(snapshot.installed):
+        location = record.get("metadata_location")
+        metadata_error = record.get("metadata_error")
+        name_value = record.get("name")
+        version_value = record.get("version")
+        if metadata_error or not isinstance(name_value, str) or not name_value.strip():
+            package = str(name_value or location or f"unknown-distribution-{index + 1}")
+            detail = str(metadata_error or "METADATA has no valid Name field")
+            issues.append(
+                Issue(
+                    "invalid_metadata",
+                    package,
+                    f"{package} has unreadable or incomplete metadata: {detail}",
+                    details={"metadata_location": location, "error": detail},
+                )
+            )
+            continue
+
+        name = name_value.strip()
+        version = str(version_value).strip() if version_value is not None else None
+        raw_requires = record.get("requires_dist")
+        requires = [str(item) for item in raw_requires] if isinstance(raw_requires, list) else []
+        requires_python_value = record.get("requires_python")
+        distribution = Distribution(
+            name=name,
+            key=canonicalize_name(name),
+            version=version,
+            requires_dist=requires,
+            requires_python=str(requires_python_value) if requires_python_value else None,
+            requested=bool(record.get("requested")),
+            metadata_location=str(location) if location else None,
+        )
+        distributions[distribution.key].append(distribution)
+
+    graph: dict[str, set[str]] = {key: set() for key in distributions}
+    incoming: dict[str, set[str]] = {key: set() for key in distributions}
+    marker_environment = _marker_environment(snapshot)
+    saw_extra_marker = False
+
+    for key, candidates in sorted(distributions.items()):
+        versions = [candidate.version or "<missing>" for candidate in candidates]
+        if len(candidates) > 1:
+            issues.append(
+                Issue(
+                    "duplicate_distribution",
+                    candidates[0].name,
+                    f"{candidates[0].name} is installed more than once: {', '.join(versions)}",
+                    installed_versions=versions,
+                    details={"metadata_locations": [item.metadata_location for item in candidates]},
+                )
+            )
+
+        for candidate in candidates:
+            if candidate.version is None:
+                issues.append(
+                    Issue(
+                        "invalid_metadata",
+                        candidate.name,
+                        f"{candidate.name} metadata has no Version field",
+                        details={"metadata_location": candidate.metadata_location},
+                    )
+                )
+            else:
+                try:
+                    Version(candidate.version)
+                except InvalidVersion:
+                    issues.append(
+                        Issue(
+                            "invalid_version",
+                            candidate.name,
+                            f"{candidate.name} has invalid installed version {candidate.version!r}",
+                            installed_versions=[candidate.version],
+                        )
+                    )
+
+            if candidate.requires_python:
+                try:
+                    python_specifier = SpecifierSet(candidate.requires_python)
+                    target_version = snapshot.environment.get("python_full_version", "")
+                    if target_version and not python_specifier.contains(target_version, prereleases=True):
+                        issues.append(
+                            Issue(
+                                "incompatible_python",
+                                candidate.name,
+                                f"{candidate.name} requires Python {candidate.requires_python}, but the target uses {target_version}",
+                                requirement=f"Python{candidate.requires_python}",
+                                installed_versions=[target_version],
+                            )
+                        )
+                except (InvalidSpecifier, InvalidVersion) as exc:
+                    issues.append(
+                        Issue(
+                            "invalid_requires_python",
+                            candidate.name,
+                            f"{candidate.name} has invalid Requires-Python metadata {candidate.requires_python!r}: {exc}",
+                            requirement=f"Python{candidate.requires_python}",
+                        )
+                    )
+
+            for requirement_text in candidate.requires_dist:
+                try:
+                    requirement = Requirement(requirement_text)
+                except InvalidRequirement as exc:
+                    issues.append(
+                        Issue(
+                            "invalid_requirement",
+                            candidate.name,
+                            f"{candidate.name} declares invalid requirement {requirement_text!r}: {exc}",
+                            requirement=requirement_text,
+                        )
+                    )
+                    continue
+
+                if requirement.marker and _EXTRA_MARKER.search(str(requirement.marker)):
+                    saw_extra_marker = True
+                    continue
+                if requirement.marker:
+                    try:
+                        if not requirement.marker.evaluate(marker_environment):
+                            continue
+                    except Exception as exc:
+                        issues.append(
+                            Issue(
+                                "invalid_marker",
+                                candidate.name,
+                                f"Could not evaluate marker in {requirement_text!r}: {exc}",
+                                requirement=requirement_text,
+                            )
+                        )
+                        continue
+
+                dependency_key = canonicalize_name(requirement.name)
+                if dependency_key in distributions:
+                    graph[key].add(dependency_key)
+                    incoming[dependency_key].add(key)
+
+                installed = distributions.get(dependency_key, [])
+                if not installed:
+                    issues.append(
+                        Issue(
+                            "missing_dependency",
+                            candidate.name,
+                            f"{candidate.name} requires {requirement}, but {requirement.name} is not installed",
+                            requirement=str(requirement),
+                            dependency=requirement.name,
+                        )
+                    )
+                    continue
+
+                valid_versions: list[Version] = []
+                installed_versions: list[str] = []
+                for dependency in installed:
+                    if dependency.version is None:
+                        continue
+                    installed_versions.append(dependency.version)
+                    try:
+                        valid_versions.append(Version(dependency.version))
+                    except InvalidVersion:
+                        pass
+
+                if requirement.specifier and valid_versions and not any(
+                    requirement.specifier.contains(version, prereleases=True) for version in valid_versions
+                ):
+                    issues.append(
+                        Issue(
+                            "incompatible_version",
+                            candidate.name,
+                            f"{candidate.name} requires {requirement}, but installed {requirement.name} version(s) are {', '.join(installed_versions)}",
+                            requirement=str(requirement),
+                            dependency=requirement.name,
+                            installed_versions=installed_versions,
+                        )
+                    )
+
+    if saw_extra_marker:
+        warnings.append(
+            "Requirements conditional on extras were skipped because installed metadata does not record which extras were selected."
+        )
+
+    roots: dict[str, str] = {}
+    for key, candidates in distributions.items():
+        if any(candidate.requested for candidate in candidates):
+            roots[key] = "recorded"
+    for key in distributions:
+        if not incoming[key] and key not in roots:
+            roots[key] = "inferred"
+
+    _attach_paths(
+        issues,
+        graph,
+        roots,
+        distributions,
+        all_paths=all_paths,
+        max_paths=max_paths,
+    )
+    issues.sort(key=lambda item: (item.code, canonicalize_name(item.package), item.requirement or ""))
+    return Report(
+        target_python=snapshot.target_python,
+        environment=snapshot.environment,
+        package_count=sum(len(values) for values in distributions.values()),
+        roots={_display_name(distributions, key): attribution for key, attribution in sorted(roots.items())},
+        issues=issues,
+        warnings=warnings,
+    )

pip_check_resolve-0.1.0/src/pip_check_resolve/cli.py

@@ -0,0 +1,70 @@
+"""Command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from . import __version__
+from .analysis import analyze
+from .probe import ProbeError, inspect_interpreter
+from .render import render_json, render_probe_error, render_text
+
+
+def _positive_integer(value: str) -> int:
+    try:
+        result = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("must be an integer") from exc
+    if result < 1:
+        raise argparse.ArgumentTypeError("must be at least 1")
+    return result
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pip-check-resolve",
+        description="Explain dependency conflicts in an installed Python environment without changing it.",
+    )
+    parser.add_argument(
+        "--python",
+        default=sys.executable,
+        metavar="PATH",
+        help="target Python interpreter (default: this interpreter)",
+    )
+    parser.add_argument(
+        "--format",
+        choices=("text", "json"),
+        default="text",
+        help="output format (default: text)",
+    )
+    parser.add_argument(
+        "--all-paths",
+        action="store_true",
+        help="show all simple causal paths instead of only shortest paths",
+    )
+    parser.add_argument(
+        "--max-paths",
+        type=_positive_integer,
+        default=20,
+        metavar="N",
+        help="maximum causal paths per issue (default: 20)",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        snapshot = inspect_interpreter(args.python)
+    except ProbeError as exc:
+        output = render_probe_error(str(exc), as_json=args.format == "json")
+        print(output, file=sys.stdout if args.format == "json" else sys.stderr)
+        return 2
+
+    report = analyze(snapshot, all_paths=args.all_paths, max_paths=args.max_paths)
+    print(render_json(report) if args.format == "json" else render_text(report))
+    return 0 if report.clean else 1
+

pip_check_resolve-0.1.0/src/pip_check_resolve/probe.py

@@ -0,0 +1,121 @@
+"""Collect metadata from a target interpreter without importing this package there."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class ProbeError(RuntimeError):
+    """The target interpreter could not return an environment snapshot."""
+
+
+@dataclass(frozen=True)
+class Snapshot:
+    target_python: str
+    environment: dict[str, str]
+    installed: list[dict[str, object]]
+
+
+# Keep this script compatible with Python 3.8: it intentionally has no dependency
+# outside the target interpreter's standard library.
+_PROBE_SCRIPT = r'''
+import importlib.metadata
+import json
+import os
+import platform
+import sys
+
+
+def text_version(info):
+    version = "%s.%s.%s" % (info.major, info.minor, info.micro)
+    if info.releaselevel != "final":
+        version += info.releaselevel[0] + str(info.serial)
+    return version
+
+
+environment = {
+    "implementation_name": sys.implementation.name,
+    "implementation_version": text_version(sys.implementation.version),
+    "os_name": os.name,
+    "platform_machine": platform.machine(),
+    "platform_release": platform.release(),
+    "platform_system": platform.system(),
+    "platform_version": platform.version(),
+    "platform_python_implementation": platform.python_implementation(),
+    "python_full_version": platform.python_version(),
+    "python_version": ".".join(platform.python_version_tuple()[:2]),
+    "sys_platform": sys.platform,
+}
+
+installed = []
+for dist in importlib.metadata.distributions():
+    record = {}
+    dist_path = getattr(dist, "_path", None)
+    if dist_path is not None:
+        record["metadata_location"] = str(dist_path)
+        try:
+            record["requested"] = (dist_path / "REQUESTED").is_file()
+        except (OSError, TypeError):
+            record["requested"] = False
+    else:
+        record["metadata_location"] = None
+        record["requested"] = False
+
+    try:
+        metadata = dist.metadata
+        record["name"] = metadata.get("Name")
+        record["version"] = metadata.get("Version")
+        record["requires_dist"] = metadata.get_all("Requires-Dist") or []
+        record["requires_python"] = metadata.get("Requires-Python")
+    except Exception as exc:
+        record["metadata_error"] = type(exc).__name__ + ": " + str(exc)
+    installed.append(record)
+
+json.dump({
+    "probe_version": 1,
+    "executable": sys.executable,
+    "environment": environment,
+    "installed": installed,
+}, sys.stdout, sort_keys=True)
+'''
+
+
+def inspect_interpreter(python: str, *, timeout: float = 30.0) -> Snapshot:
+    """Run the metadata probe under *python* and return its parsed snapshot."""
+
+    try:
+        completed = subprocess.run(
+            [python, "-I", "-c", _PROBE_SCRIPT],
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except FileNotFoundError as exc:
+        raise ProbeError(f"Python interpreter not found: {python}") from exc
+    except PermissionError as exc:
+        raise ProbeError(f"Python interpreter is not executable: {python}") from exc
+    except subprocess.TimeoutExpired as exc:
+        raise ProbeError(f"Timed out inspecting {python} after {timeout:g} seconds") from exc
+    except OSError as exc:
+        raise ProbeError(f"Could not run {python}: {exc}") from exc
+
+    if completed.returncode != 0:
+        detail = completed.stderr.strip() or completed.stdout.strip() or "no error output"
+        raise ProbeError(f"Target interpreter exited with {completed.returncode}: {detail}")
+
+    try:
+        data = json.loads(completed.stdout)
+    except (json.JSONDecodeError, TypeError) as exc:
+        raise ProbeError(f"Target interpreter returned invalid probe data: {exc}") from exc
+
+    if data.get("probe_version") != 1:
+        raise ProbeError("Target interpreter returned an unsupported probe version")
+    if not isinstance(data.get("environment"), dict) or not isinstance(data.get("installed"), list):
+        raise ProbeError("Target interpreter returned an incomplete probe snapshot")
+
+    executable = str(data.get("executable") or Path(python))
+    return Snapshot(executable, data["environment"], data["installed"])

pip_check_resolve-0.1.0/src/pip_check_resolve/render.py

@@ -0,0 +1,95 @@
+"""Render analysis reports for humans and automation."""
+
+from __future__ import annotations
+
+import json
+
+from .analysis import Report
+
+
+def report_data(report: Report) -> dict[str, object]:
+    return {
+        "schema_version": 1,
+        "status": "clean" if report.clean else "issues",
+        "target_python": report.target_python,
+        "environment": report.environment,
+        "summary": {
+            "package_count": report.package_count,
+            "issue_count": len(report.issues),
+            "warning_count": len(report.warnings),
+        },
+        "roots": [
+            {"name": name, "attribution": attribution}
+            for name, attribution in sorted(report.roots.items(), key=lambda item: item[0].lower())
+        ],
+        "issues": [
+            {
+                "code": issue.code,
+                "package": issue.package,
+                "message": issue.message,
+                "requirement": issue.requirement,
+                "dependency": issue.dependency,
+                "installed_versions": issue.installed_versions,
+                "paths": [
+                    {
+                        "root": path.root,
+                        "root_attribution": path.root_attribution,
+                        "packages": path.packages,
+                    }
+                    for path in issue.paths
+                ],
+                "paths_truncated": issue.paths_truncated,
+                "details": issue.details,
+            }
+            for issue in report.issues
+        ],
+        "warnings": report.warnings,
+    }
+
+
+def render_json(report: Report) -> str:
+    return json.dumps(report_data(report), indent=2, sort_keys=True)
+
+
+def render_text(report: Report) -> str:
+    python_version = report.environment.get("python_full_version", "unknown")
+    if report.clean:
+        lines = [
+            f"No dependency conflicts found among {report.package_count} packages ",
+            f"in Python {python_version} ({report.target_python}).",
+        ]
+        # Keep the success sentence together while preserving a readable source file.
+        lines = ["".join(lines)]
+    else:
+        noun = "issue" if len(report.issues) == 1 else "issues"
+        lines = [
+            f"Found {len(report.issues)} dependency {noun} among {report.package_count} packages ",
+            f"in Python {python_version} ({report.target_python}).",
+        ]
+        lines = ["".join(lines), ""]
+        for issue in report.issues:
+            lines.append(f"[{issue.code.upper()}] {issue.message}")
+            for path in issue.paths:
+                chain = " -> ".join(path.packages)
+                lines.append(f"  via ({path.root_attribution} root) {chain}")
+            if issue.paths_truncated:
+                lines.append("  Additional causal paths were truncated.")
+            lines.append("")
+        if lines[-1] == "":
+            lines.pop()
+
+    if report.warnings:
+        lines.extend(["", "Warnings:"])
+        lines.extend(f"  - {warning}" for warning in report.warnings)
+    return "\n".join(lines)
+
+
+def render_probe_error(message: str, *, as_json: bool) -> str:
+    if as_json:
+        return json.dumps(
+            {"schema_version": 1, "status": "error", "error": {"code": "probe_failed", "message": message}},
+            indent=2,
+            sort_keys=True,
+        )
+    return f"error: {message}"
+

pip_check_resolve-0.1.0/src/pip_check_resolve.egg-info/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: pip-check-resolve
+Version: 0.1.0
+Summary: Explain installed Python dependency conflicts and their causal paths
+Project-URL: Homepage, https://github.com/matplo/pip-check-resolve
+Project-URL: Repository, https://github.com/matplo/pip-check-resolve
+Project-URL: Issues, https://github.com/matplo/pip-check-resolve/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: packaging>=24
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+
+# pip-check-resolve
+
+`pip-check-resolve` inspects an installed Python environment without changing it.
+It finds missing or incompatible dependencies and traces each problem back to the
+likely top-level packages that caused it.
+
+Unlike a resolver, it answers **why the environment that exists now is broken**.
+It does not install packages, try alternative versions, or contact PyPI.
+
+## Usage
+
+Run inside the environment to inspect the current interpreter:
+
+```console
+$ pip-check-resolve
+```
+
+Or keep the tool isolated and point it at another environment:
+
+```console
+$ uvx --from pip-check-resolve pip-check-resolve --python .venv/bin/python
+```
+
+Machine-readable output and expanded causal paths are available:
+
+```console
+$ pip-check-resolve --python .venv/bin/python --format json
+$ pip-check-resolve --all-paths --max-paths 100
+```
+
+Exit status is `0` for a consistent environment, `1` when package or metadata
+issues are found, and `2` when the target interpreter cannot be inspected.
+
+## What is checked
+
+- missing dependencies;
+- versions that do not satisfy their declared requirements;
+- incompatible `Requires-Python` metadata;
+- duplicate normalized distribution names;
+- malformed package requirements or metadata.
+
+Roots are identified from a distribution's `REQUESTED` marker when available and
+otherwise inferred from the installed dependency graph. Python packaging does not
+reliably preserve which extras were requested, so requirements conditional on
+`extra` are skipped and the report records that limitation.
+
+## Releasing
+
+Releases are published from GitHub tags using PyPI Trusted Publishing. The tag
+must be the project version prefixed with `v`, for example `v0.1.0`. Update the
+version in both `pyproject.toml` and `src/pip_check_resolve/__init__.py`, commit,
+and then create and push the matching tag:
+
+```console
+$ git tag v0.1.0
+$ git push origin v0.1.0
+```
+
+The `publish.yml` workflow tests the package, builds and checks its wheel and
+source distribution, and publishes them to PyPI using short-lived OIDC
+credentials. The PyPI Trusted Publisher must use owner `matplo`, repository
+`pip-check-resolve`, workflow `publish.yml`, and environment `pypi`.
+

pip_check_resolve-0.1.0/src/pip_check_resolve.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+src/pip_check_resolve/__init__.py
+src/pip_check_resolve/__main__.py
+src/pip_check_resolve/analysis.py
+src/pip_check_resolve/cli.py
+src/pip_check_resolve/probe.py
+src/pip_check_resolve/render.py
+src/pip_check_resolve.egg-info/PKG-INFO
+src/pip_check_resolve.egg-info/SOURCES.txt
+src/pip_check_resolve.egg-info/dependency_links.txt
+src/pip_check_resolve.egg-info/entry_points.txt
+src/pip_check_resolve.egg-info/requires.txt
+src/pip_check_resolve.egg-info/top_level.txt
+tests/test_analysis.py
+tests/test_cli.py

pip_check_resolve-0.1.0/src/pip_check_resolve.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pip_check_resolve-0.1.0/src/pip_check_resolve.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pip-check-resolve = pip_check_resolve.cli:main

pip_check_resolve-0.1.0/src/pip_check_resolve.egg-info/requires.txt

@@ -0,0 +1,4 @@
+packaging>=24
+
+[test]
+pytest>=8

pip_check_resolve-0.1.0/src/pip_check_resolve.egg-info/top_level.txt

@@ -0,0 +1 @@
+pip_check_resolve

pip_check_resolve-0.1.0/tests/test_analysis.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+from pip_check_resolve.analysis import analyze
+from pip_check_resolve.probe import Snapshot
+from pip_check_resolve.render import report_data, render_text
+
+
+ENVIRONMENT = {
+    "implementation_name": "cpython",
+    "implementation_version": "3.12.4",
+    "os_name": "posix",
+    "platform_machine": "x86_64",
+    "platform_release": "test",
+    "platform_system": "Linux",
+    "platform_version": "test",
+    "platform_python_implementation": "CPython",
+    "python_full_version": "3.12.4",
+    "python_version": "3.12",
+    "sys_platform": "linux",
+}
+
+
+def dist(
+    name: str,
+    version: str = "1.0",
+    *,
+    requires: list[str] | None = None,
+    requested: bool = False,
+    requires_python: str | None = None,
+    location: str | None = None,
+) -> dict[str, object]:
+    return {
+        "name": name,
+        "version": version,
+        "requires_dist": requires or [],
+        "requires_python": requires_python,
+        "requested": requested,
+        "metadata_location": location or f"/site/{name}-{version}.dist-info",
+    }
+
+
+def snapshot(*installed: dict[str, object]) -> Snapshot:
+    return Snapshot("/venv/bin/python", ENVIRONMENT.copy(), list(installed))
+
+
+def test_clean_transitive_graph() -> None:
+    report = analyze(
+        snapshot(
+            dist("app", requires=["middle>=1"], requested=True),
+            dist("middle", requires=["leaf<2"]),
+            dist("leaf", "1.5"),
+        )
+    )
+
+    assert report.clean
+    assert report.roots == {"app": "recorded"}
+    assert report_data(report)["status"] == "clean"
+
+
+def test_conflict_has_shortest_path_from_recorded_root() -> None:
+    report = analyze(
+        snapshot(
+            dist("app", requires=["middle"], requested=True),
+            dist("middle", requires=["leaf<2"]),
+            dist("leaf", "3.0"),
+        )
+    )
+
+    assert len(report.issues) == 1
+    issue = report.issues[0]
+    assert issue.code == "incompatible_version"
+    assert issue.paths[0].packages == ["app", "middle"]
+    assert issue.paths[0].root_attribution == "recorded"
+    assert "app -> middle" in render_text(report)
+
+
+def test_missing_dependency_and_inferred_root() -> None:
+    report = analyze(snapshot(dist("plugin", requires=["missing>=4"])))
+
+    assert report.roots == {"plugin": "inferred"}
+    assert report.issues[0].code == "missing_dependency"
+    assert report.issues[0].dependency == "missing"
+    assert report.issues[0].paths[0].packages == ["plugin"]
+
+
+def test_environment_markers_and_extras() -> None:
+    report = analyze(
+        snapshot(
+            dist(
+                "app",
+                requires=[
+                    "windows-only; sys_platform == 'win32'",
+                    "speedup; extra == 'fast'",
+                    "present; python_version >= '3.10'",
+                ],
+                requested=True,
+            ),
+            dist("present"),
+        )
+    )
+
+    assert report.clean
+    assert len(report.warnings) == 1
+    assert "extras" in report.warnings[0]
+
+
+def test_literal_word_extra_is_not_treated_as_an_extras_marker() -> None:
+    environment = ENVIRONMENT.copy()
+    environment["os_name"] = "extra"
+    report = analyze(
+        Snapshot(
+            "/venv/bin/python",
+            environment,
+            [dist("app", requires=['required; os_name == "extra"'], requested=True)],
+        )
+    )
+
+    assert report.issues[0].code == "missing_dependency"
+    assert not report.warnings
+
+
+def test_duplicate_and_incompatible_python_are_reported() -> None:
+    report = analyze(
+        snapshot(
+            dist("same-name", "1", requested=True, location="/one"),
+            dist("Same_Name", "2", location="/two"),
+            dist("future", requires_python=">=3.13"),
+        )
+    )
+
+    assert {issue.code for issue in report.issues} == {
+        "duplicate_distribution",
+        "incompatible_python",
+    }
+
+
+def test_invalid_metadata_requirement_and_version() -> None:
+    broken_metadata = {"metadata_location": "/broken", "metadata_error": "ValueError: bad"}
+    report = analyze(
+        snapshot(
+            broken_metadata,
+            dist("bad-version", "not a version"),
+            dist("bad-requirement", requires=["???"]),
+        )
+    )
+
+    assert {issue.code for issue in report.issues} == {
+        "invalid_metadata",
+        "invalid_requirement",
+        "invalid_version",
+    }
+
+
+def test_all_paths_are_cycle_safe_and_capped() -> None:
+    graph_snapshot = snapshot(
+        dist("root", requires=["left", "right"], requested=True),
+        dist("left", requires=["middle"]),
+        dist("right", requires=["middle"]),
+        dist("middle", requires=["left", "missing"]),
+    )
+
+    complete = analyze(graph_snapshot, all_paths=True, max_paths=10)
+    issue = next(item for item in complete.issues if item.code == "missing_dependency")
+    assert {tuple(path.packages) for path in issue.paths} == {
+        ("root", "left", "middle"),
+        ("root", "right", "middle"),
+    }
+    assert not issue.paths_truncated
+
+    capped = analyze(graph_snapshot, all_paths=True, max_paths=1)
+    capped_issue = next(item for item in capped.issues if item.code == "missing_dependency")
+    assert len(capped_issue.paths) == 1
+    assert capped_issue.paths_truncated
+
+
+def test_multiple_shortest_paths_for_one_root() -> None:
+    report = analyze(
+        snapshot(
+            dist("root", requires=["left", "right"], requested=True),
+            dist("left", requires=["target"]),
+            dist("right", requires=["target"]),
+            dist("target", requires=["absent"]),
+        )
+    )
+    issue = report.issues[0]
+
+    assert {tuple(path.packages) for path in issue.paths} == {
+        ("root", "left", "target"),
+        ("root", "right", "target"),
+    }

pip_check_resolve-0.1.0/tests/test_cli.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import subprocess
+import sys
+import venv
+
+from pip_check_resolve.analysis import analyze
+from pip_check_resolve.cli import main
+from pip_check_resolve.probe import inspect_interpreter
+
+
+def test_probe_current_interpreter() -> None:
+    result = inspect_interpreter(sys.executable)
+
+    assert result.target_python
+    assert result.environment["python_full_version"]
+    assert isinstance(result.installed, list)
+
+
+def test_missing_interpreter_is_operational_error(capsys) -> None:
+    exit_code = main(["--python", "/definitely/not/a/python", "--format", "json"])
+    output = json.loads(capsys.readouterr().out)
+
+    assert exit_code == 2
+    assert output["status"] == "error"
+    assert output["error"]["code"] == "probe_failed"
+
+
+def test_invalid_max_paths_is_usage_error() -> None:
+    try:
+        main(["--max-paths", "0"])
+    except SystemExit as exc:
+        assert exc.code == 2
+    else:
+        raise AssertionError("argparse did not reject --max-paths 0")
+
+
+def test_external_environment_without_pip_is_inspected_without_changes(tmp_path: Path) -> None:
+    environment_dir = tmp_path / "target environment"
+    venv.EnvBuilder(with_pip=False).create(environment_dir)
+    executable = environment_dir / ("Scripts/python.exe" if sys.platform == "win32" else "bin/python")
+    purelib = Path(
+        subprocess.check_output(
+            [str(executable), "-c", "import sysconfig; print(sysconfig.get_path('purelib'))"],
+            text=True,
+        ).strip()
+    )
+    metadata_dir = purelib / "demo_app-1.0.dist-info"
+    metadata_dir.mkdir()
+    metadata = metadata_dir / "METADATA"
+    metadata.write_text(
+        "Metadata-Version: 2.1\nName: demo-app\nVersion: 1.0\nRequires-Dist: absent>=2\n",
+        encoding="utf-8",
+    )
+    (metadata_dir / "REQUESTED").touch()
+    before = metadata.read_bytes()
+
+    report = analyze(inspect_interpreter(str(executable)))
+
+    assert report.issues[0].code == "missing_dependency"
+    assert report.issues[0].paths[0].root_attribution == "recorded"
+    assert metadata.read_bytes() == before
+    assert not (purelib / "pip").exists()