req-compile 1.2.0__tar.gz → 1.4.0__tar.gz

{req_compile-1.2.0 → req_compile-1.4.0}/CHANGELOG.rst

@@ -1,5 +1,33 @@
+New in version 1.3.1:
+
+* ``py_reqs_compiler`` compiles the solutions of several platforms together: ``requirements_txts`` maps a
+  solution file to each platform. The solutions use the same version of every package, a package keeps the
+  version the first platform resolves it to and a version another platform cannot use is dropped for all of
+  them. The compilation fails, naming the platforms, when no version of a package works everywhere. A
+  ``py_reqs_solution_test`` of such a target checks every solution, including that they agree.
+* The Bazel compiler accepts ``--solution``, ``--platform`` and ``--output`` once per solution.
+* ``perform_compile`` accepts soft pins, which yield with ``PinConflictException`` when a package cannot
+  satisfy them, and ``perform_compile_group`` compiles the same requirements for several targets with one
+  version per package.
+
 New in version 1.2.0:
 
+* ``requirements.parse`` now maps lock files to ids in ``requirements_locks`` and config settings to those
+  ids in the new ``config_settings`` attribute. Both are label keyed, so each is resolved by the module
+  defining the hub and any config setting visible to it can be used. ``//conditions:default`` names a
+  fallback lock. Without ``config_settings``, locks compiled with the ``platform`` attribute of
+  ``py_reqs_compiler`` are selected by the platform read from the header of the file. Label strings as
+  ``requirements_locks`` values still work but are deprecated.
+* Every distinct wheel is downloaded once into a repository named ``{package}_{version}_{sha256[:8]}``
+  and shared by all hubs of all modules pinning it. Each hub keeps its own dependency edges, so extras
+  and version differences between hubs are preserved. Hub names must be unique across modules.
+* ``package_annotation`` applies to the hubs of the module declaring it unless its new ``hubs``
+  attribute names particular hubs or ``"*"`` for every hub. Hubs annotated differently get their own
+  repository for the package.
+* Hubs whose locks do not all contain the same packages are supported. A package missing from a lock
+  is incompatible with that lock's platform, so targets depending on it are skipped there.
+* Removed the ``defs_id_map`` attribute of the ``parse`` tag and the WORKSPACE-only ``repositories()``
+  flow. ``py_requirements_repository`` is now only instantiated by the module extension.
 * Cross-platform compilation. ``--platform``, ``--python-version`` and ``--implementation`` select
   wheels and evaluate environment markers for an environment other than the one running ``req-compile``.
   ``--platform`` takes a wheel platform tag such as ``manylinux_2_28_x86_64`` or ``macosx_11_0_arm64``,

{req_compile-1.2.0 → req_compile-1.4.0}/MANIFEST.in

@@ -1,5 +1,10 @@
 include *.py
-prune tests private .idea requirements.txt
+prune tests
+prune examples
+prune rule_tests
+prune req_compile/private
+prune .idea
+exclude requirements.txt
 include CHANGELOG.rst
 include LICENSE.txt
 include pyproject.toml

{req_compile-1.2.0/req_compile.egg-info → req_compile-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: req-compile
-Version: 1.2.0
+Version: 1.4.0
 Summary: Python requirements compiler
 Home-page: https://github.com/periareon/req-compile
 Author: Spencer Putt
@@ -38,8 +38,36 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
+New in version 1.3.1:
+
+* ``py_reqs_compiler`` compiles the solutions of several platforms together: ``requirements_txts`` maps a
+  solution file to each platform. The solutions use the same version of every package, a package keeps the
+  version the first platform resolves it to and a version another platform cannot use is dropped for all of
+  them. The compilation fails, naming the platforms, when no version of a package works everywhere. A
+  ``py_reqs_solution_test`` of such a target checks every solution, including that they agree.
+* The Bazel compiler accepts ``--solution``, ``--platform`` and ``--output`` once per solution.
+* ``perform_compile`` accepts soft pins, which yield with ``PinConflictException`` when a package cannot
+  satisfy them, and ``perform_compile_group`` compiles the same requirements for several targets with one
+  version per package.
+
 New in version 1.2.0:
 
+* ``requirements.parse`` now maps lock files to ids in ``requirements_locks`` and config settings to those
+  ids in the new ``config_settings`` attribute. Both are label keyed, so each is resolved by the module
+  defining the hub and any config setting visible to it can be used. ``//conditions:default`` names a
+  fallback lock. Without ``config_settings``, locks compiled with the ``platform`` attribute of
+  ``py_reqs_compiler`` are selected by the platform read from the header of the file. Label strings as
+  ``requirements_locks`` values still work but are deprecated.
+* Every distinct wheel is downloaded once into a repository named ``{package}_{version}_{sha256[:8]}``
+  and shared by all hubs of all modules pinning it. Each hub keeps its own dependency edges, so extras
+  and version differences between hubs are preserved. Hub names must be unique across modules.
+* ``package_annotation`` applies to the hubs of the module declaring it unless its new ``hubs``
+  attribute names particular hubs or ``"*"`` for every hub. Hubs annotated differently get their own
+  repository for the package.
+* Hubs whose locks do not all contain the same packages are supported. A package missing from a lock
+  is incompatible with that lock's platform, so targets depending on it are skipped there.
+* Removed the ``defs_id_map`` attribute of the ``parse`` tag and the WORKSPACE-only ``repositories()``
+  flow. ``py_requirements_repository`` is now only instantiated by the module extension.
 * Cross-platform compilation. ``--platform``, ``--python-version`` and ``--implementation`` select
   wheels and evaluate environment markers for an environment other than the one running ``req-compile``.
   ``--platform`` takes a wheel platform tag such as ``manylinux_2_28_x86_64`` or ``macosx_11_0_arm64``,
@@ -114,19 +142,26 @@ To get started with Bazel, add the following to your ``MODULE.bazel`` file:
     # Find {version} on the req-compile GitHub releases page.
     bazel_dep(name = "rules_req_compile", version = "{version}")
 
-    requirements = use_extension("//extensions:python.bzl", "requirements")
+    requirements = use_extension("@rules_req_compile//extensions:python.bzl", "requirements")
     requirements.parse(
         name = "my_pip_deps",
         requirements_locks = {
-            "//3rdparty:requirements.linux.txt": "@platforms//os:linux",
-            "//3rdparty:requirements.macos.txt": "@platforms//os:macos",
-            "//3rdparty:requirements.windows.txt": "@platforms//os:windows",
+            "//3rdparty:requirements.linux_x86_64.txt": "linux_x86_64",
+            "//3rdparty:requirements.macos_aarch64.txt": "macos_aarch64",
+            "//3rdparty:requirements.windows_x86_64.txt": "windows_x86_64",
         },
     )
     use_repo(requirements, "my_pip_deps")
 
-The solutions for every platform can be compiled from a single machine with the ``platform`` attribute of
-``py_reqs_compiler``. See the `Bazel rules documentation <docs/docs.md>`_ for details.
+Each lock is the solution for one platform and is given an id. Locks compiled with the ``platform``
+attribute of ``py_reqs_compiler`` record their platform, which is used to select them. To decide
+yourself, map your own ``config_setting`` labels to the lock ids with ``config_settings``. The solutions
+for every platform can be compiled from a single machine.
+
+Every wheel is downloaded once and shared by all the hubs of all the modules pinning it, while each hub
+keeps the dependencies it resolved. Packages missing from the lock of a platform make the targets using
+them incompatible with that platform instead of failing the build.
+See the `Bazel rules documentation <docs/docs.md>`_ for details.
 
 
 Why use it?

{req_compile-1.2.0 → req_compile-1.4.0}/README.rst

@@ -36,19 +36,26 @@ To get started with Bazel, add the following to your ``MODULE.bazel`` file:
     # Find {version} on the req-compile GitHub releases page.
     bazel_dep(name = "rules_req_compile", version = "{version}")
 
-    requirements = use_extension("//extensions:python.bzl", "requirements")
+    requirements = use_extension("@rules_req_compile//extensions:python.bzl", "requirements")
     requirements.parse(
         name = "my_pip_deps",
         requirements_locks = {
-            "//3rdparty:requirements.linux.txt": "@platforms//os:linux",
-            "//3rdparty:requirements.macos.txt": "@platforms//os:macos",
-            "//3rdparty:requirements.windows.txt": "@platforms//os:windows",
+            "//3rdparty:requirements.linux_x86_64.txt": "linux_x86_64",
+            "//3rdparty:requirements.macos_aarch64.txt": "macos_aarch64",
+            "//3rdparty:requirements.windows_x86_64.txt": "windows_x86_64",
         },
     )
     use_repo(requirements, "my_pip_deps")
 
-The solutions for every platform can be compiled from a single machine with the ``platform`` attribute of
-``py_reqs_compiler``. See the `Bazel rules documentation <docs/docs.md>`_ for details.
+Each lock is the solution for one platform and is given an id. Locks compiled with the ``platform``
+attribute of ``py_reqs_compiler`` record their platform, which is used to select them. To decide
+yourself, map your own ``config_setting`` labels to the lock ids with ``config_settings``. The solutions
+for every platform can be compiled from a single machine.
+
+Every wheel is downloaded once and shared by all the hubs of all the modules pinning it, while each hub
+keeps the dependencies it resolved. Packages missing from the lock of a platform make the targets using
+them incompatible with that platform instead of failing the build.
+See the `Bazel rules documentation <docs/docs.md>`_ for details.
 
 
 Why use it?

{req_compile-1.2.0 → req_compile-1.4.0}/pyproject.toml

@@ -2,8 +2,13 @@
 requires = ["setuptools", "wheel"]
 build-backend = "setuptools.build_meta"
 
+[tool.isort]
+profile = "black"
+
 [tool.mypy]
-namespace_packages = false
+# `req_compile.private` deliberately has no `__init__.py` so that `setup.py`'s
+# `find_packages` leaves the Bazel rule helpers out of the distribution.
+namespace_packages = true
 
 [tool.pylint.main]
 max-line-length = 120
@@ -21,6 +26,3 @@ disable = [
     "consider-using-f-string",
     "useless-import-alias",  # Conflict with ruff check.
 ]
-
-[tool.isort]
-profile = "black"

{req_compile-1.2.0 → req_compile-1.4.0}/req_compile/compile.py

@@ -6,15 +6,22 @@ import logging
 import operator
 import os
 from collections import defaultdict
-from typing import Dict, Iterable, Mapping, Optional, Set, Tuple
+from typing import Dict, Iterable, List, Mapping, Optional, Sequence, Set, Tuple
 
 import packaging.requirements
+import packaging.version
 
 import req_compile.containers
 import req_compile.dists
 from req_compile.containers import RequirementContainer
 from req_compile.dists import DependencyNode, DistributionCollection
-from req_compile.errors import MetadataError, NoCandidateException
+from req_compile.errors import (
+    MetadataError,
+    NoCandidateException,
+    NoCommonVersionException,
+    PinConflictException,
+    Rejection,
+)
 from req_compile.repos.repository import Repository
 from req_compile.repos.source import SourceRepository
 from req_compile.target import TargetEnvironment
@@ -30,6 +37,9 @@ from req_compile.versions import is_possible
 
 MAX_COMPILE_DEPTH = int(os.environ.get("REQ_COMPILE_MAX_DEPTH", "80"))
 MAX_DOWNGRADE = int(os.environ.get("REQ_COMPILE_MAX_DOWNGRADE", "20"))
+# The number of times solutions compiled together are resolved again after one
+# of them rejected a version another had chosen.
+MAX_GROUP_PASSES = int(os.environ.get("REQ_COMPILE_MAX_GROUP_PASSES", "20"))
 
 LOG = logging.getLogger("req_compile.compile")
 
@@ -50,14 +60,24 @@ class CompileOptions:
     extras: Optional[Iterable[str]] = None
     allow_circular_dependencies: bool = True
     pinned_requirements: Mapping[NormName, packaging.requirements.Requirement] = {}
+    # Requirements applied to a project only if it is required, which yield when
+    # the project cannot satisfy them: `PinConflictException` is raised instead of
+    # resolving the reverse dependencies differently. Solutions compiled together
+    # use these to keep their versions aligned, see `perform_compile_group`.
+    soft_pins: Mapping[NormName, packaging.requirements.Requirement] = {}
     only_binary: Set[NormName] = set()
 
 
-def _get_strictest_reverse_dep(node: DependencyNode) -> Optional[DependencyNode]:
+def _get_strictest_reverse_dep(
+    node: DependencyNode,
+    soft_pin: Optional[packaging.requirements.Requirement] = None,
+) -> Optional[DependencyNode]:
     """Get the strictest constraint from all reverse dependencies.
 
     Args:
         node: The node to check.
+        soft_pin: A soft pin on the node, scored like a reverse dependency that
+            cannot itself be walked back.
 
     Returns:
         The single reverse dependency that was the most conflicting. If no reverse
@@ -67,6 +87,10 @@ def _get_strictest_reverse_dep(node: DependencyNode) -> Optional[DependencyNode]
 
     violate_score: Dict[DependencyNode, int] = defaultdict(int)
     for idx, revnode in enumerate(nodes):
+        if soft_pin is not None and not is_possible(
+            merge_requirements(revnode.dependencies[node], soft_pin)
+        ):
+            violate_score[revnode] += 1
         for next_node in nodes[idx + 1 :]:
             if not is_possible(
                 merge_requirements(
@@ -158,6 +182,20 @@ def compile_roots(
             pin = options.pinned_requirements.get(spec_name, spec_req)
             spec_req = merge_requirements(spec_req, pin)
 
+        # The requirement before any soft pin, which decides whether a failure is
+        # the pin's fault.
+        unpinned_req = spec_req
+        soft_pin = options.soft_pins.get(spec_name)
+        if soft_pin is not None:
+            spec_req = merge_requirements(spec_req, soft_pin)
+
+        def _no_candidate(no_candidate: bool) -> NoCandidateException:
+            if soft_pin is not None and is_possible(unpinned_req):
+                return PinConflictException(
+                    spec_name, soft_pin, unpinned_req, node, no_candidate
+                )
+            return NoCandidateException(spec_req)
+
         if not is_possible(spec_req):
             logger.info("Requirement conflict for %s (%s)", node, spec_req)
             # Try walking back. Some reverse dependency contributed a requirement
@@ -167,13 +205,13 @@ def compile_roots(
             # version from being selected.
             # Search the full space is expensive and possibly harmful because of how heavily
             # it must hit remote indices.
-            reverse_dep = _get_strictest_reverse_dep(node)
+            reverse_dep = _get_strictest_reverse_dep(node, soft_pin)
             if (
                 reverse_dep is None
                 or reverse_dep.metadata is None
                 or reverse_dep.metadata.version is None
             ):
-                raise NoCandidateException(spec_req)
+                raise _no_candidate(no_candidate=False)
 
             if _walkback_budget is not None and _walkback_budget <= 0:
                 logger.info(
@@ -181,7 +219,7 @@ def compile_roots(
                     node,
                     spec_req,
                 )
-                ex = NoCandidateException(spec_req)
+                ex = _no_candidate(no_candidate=False)
                 ex.conflicting_node = node
                 ex.walkback_project = reverse_dep.metadata.name
                 raise ex
@@ -241,11 +279,22 @@ def compile_roots(
                 dists.remove_dists(bad_constraint, remove_upstream=False)
             return
 
-        metadata, cached = repo.get_dist(
-            spec_req,
-            allow_source_dist=spec_name not in options.only_binary,
-            max_downgrade=max_downgrade,
-        )
+        try:
+            metadata, cached = repo.get_dist(
+                spec_req,
+                allow_source_dist=spec_name not in options.only_binary,
+                max_downgrade=max_downgrade,
+            )
+        except NoCandidateException:
+            if soft_pin is None:
+                raise
+            # The pin is only at fault if the requirement is solvable without it.
+            repo.get_dist(
+                unpinned_req,
+                allow_source_dist=spec_name not in options.only_binary,
+                max_downgrade=max_downgrade,
+            )
+            raise _no_candidate(no_candidate=True) from None
         logger.debug(
             "Acquired candidate %s %s [%s] (%s)",
             metadata,
@@ -312,6 +361,7 @@ def perform_compile(
     only_binary: Optional[Set[NormName]] = None,
     max_downgrade: Optional[int] = None,
     target: Optional[TargetEnvironment] = None,
+    pins: Optional[Mapping[NormName, packaging.requirements.Requirement]] = None,
 ) -> Tuple[DistributionCollection, Set[DependencyNode]]:
     """Perform a compilation using the given inputs and constraints.
 
@@ -331,6 +381,11 @@ def perform_compile(
         max_downgrade: The maximum number of version downgrades that will be allowed for conflicts.
         target: The environment to compile for. Defaults to the target of `repo`, which
             itself defaults to the host.
+        pins: Soft pins keyed by normalized name. Unlike constraints, a soft pin
+            never requires a package, is not recorded in the solution and yields
+            when the package cannot satisfy it: `PinConflictException` is raised
+            instead of resolving the dependents differently. See
+            `CompileOptions.soft_pins`.
 
     Returns:
         the solution and root nodes used to generate it
@@ -370,6 +425,7 @@ def perform_compile(
     if all_pinned and constraint_reqs:
         LOG.info("All constraints were pins - no need to solve the constraints")
         options.pinned_requirements = pinned_requirements
+    options.soft_pins = dict(pins or {})
 
     if max_downgrade is None:
         max_downgrade = MAX_DOWNGRADE
@@ -402,6 +458,148 @@ def perform_compile(
     return results, roots
 
 
+def _soft_pins(
+    agreed: Mapping[NormName, packaging.version.Version],
+    rejected: Mapping[NormName, Sequence[Rejection]],
+) -> Dict[NormName, packaging.requirements.Requirement]:
+    """The soft pins keeping solutions compiled together aligned.
+
+    A project with an agreed version is pinned to it. A project without one, whose
+    versions some solution rejected, is kept away from those versions.
+    """
+    pins = {}
+    for name, version in agreed.items():
+        pins[name] = parse_requirement(f"{name}=={version}")
+    for name, rejections in rejected.items():
+        if name in agreed or not rejections:
+            continue
+        pins[name] = parse_requirement(
+            name + ",".join(f"!={rejection.version}" for rejection in rejections)
+        )
+    return pins
+
+
+def perform_compile_group(
+    input_reqs: Iterable[RequirementContainer],
+    repos: Sequence[Repository],
+    constraint_reqs: Optional[Iterable[RequirementContainer]] = None,
+    remove_constraints: bool = False,
+    extras: Optional[Iterable[str]] = None,
+    allow_circular_dependencies: bool = True,
+    only_binary: Optional[Set[NormName]] = None,
+    max_downgrade: Optional[int] = None,
+    pins: Optional[Mapping[NormName, packaging.version.Version]] = None,
+    max_passes: int = MAX_GROUP_PASSES,
+) -> List[Tuple[DistributionCollection, Set[DependencyNode]]]:
+    """Compile the same requirements for several targets, with one version per project.
+
+    Each repository is compiled for its own target, in order. A project keeps the
+    version the first target that needs it resolves it to, so the solutions never
+    disagree. When a later target cannot use that version at all, e.g. there is no
+    artifact for its platform or its dependencies require another version, the
+    version is rejected for every target and the group is compiled again, until a
+    pass completes without any rejection. A target may also resolve the dependents
+    of a pinned project to other versions than an earlier target did rather than
+    reject the version, in which case the next pass aligns the earlier target.
+
+    Args:
+        input_reqs: The requirements, shared by every target.
+        repos: One repository per target, compiled in this order. Each compiles for
+            its own target, see `Repository.target`.
+        constraint_reqs: Constraints to use when compiling.
+        remove_constraints: Whether to remove the constraints from the solutions.
+        extras: Extras to apply automatically to source projects.
+        allow_circular_dependencies: Whether to allow circular dependencies.
+        only_binary: Set of projects that should only consider binary distributions.
+        max_downgrade: The maximum number of version downgrades that will be allowed
+            for conflicts, and the maximum number of versions of a project the
+            targets may reject before giving up.
+        pins: Versions to start from, keyed by normalized name, e.g. those of the
+            solutions being recompiled. They are soft pins: a project is only pinned
+            if it is required, and a version that a target cannot use is rejected
+            like any other.
+        max_passes: The maximum number of times the group is compiled.
+
+    Returns:
+        The solution and root nodes of each repository, in the order given.
+
+    Raises:
+        NoCommonVersionException: If no version of a project can be used by every
+            target that needs it.
+        NoCandidateException: If the requirements cannot be resolved for a target.
+    """
+    input_reqs = list(input_reqs)
+    if max_downgrade is None:
+        max_downgrade = MAX_DOWNGRADE
+    agreed: Dict[NormName, packaging.version.Version] = dict(pins or {})
+    rejected: Dict[NormName, List[Rejection]] = defaultdict(list)
+    last: Optional[Rejection] = None
+
+    for _ in range(max_passes):
+        rejections = 0
+        results: List[Tuple[DistributionCollection, Set[DependencyNode]]] = []
+        for repo in repos:
+            target = repo.target
+            while True:
+                try:
+                    results.append(
+                        perform_compile(
+                            input_reqs,
+                            repo,
+                            constraint_reqs=constraint_reqs,
+                            remove_constraints=remove_constraints,
+                            extras=extras,
+                            allow_circular_dependencies=allow_circular_dependencies,
+                            only_binary=only_binary,
+                            max_downgrade=max_downgrade,
+                            target=target,
+                            pins=_soft_pins(agreed, rejected),
+                        )
+                    )
+                    break
+                except PinConflictException as ex:
+                    rejections += 1
+                    version = agreed.pop(ex.name, None)
+                    rejected[ex.name].append(Rejection(target, version, ex))
+                    if version is None or len(rejected[ex.name]) > max_downgrade:
+                        # Every version this target can use was rejected by
+                        # another, or the search is not converging.
+                        raise NoCommonVersionException(
+                            ex.name, rejected[ex.name]
+                        ) from ex
+                    LOG.info(
+                        "%s cannot use %s (%s), resolving it again for every target",
+                        target.name,
+                        ex.pin,
+                        ex,
+                    )
+                    last = rejected[ex.name][-1]
+
+            for node in results[-1][0]:
+                if (
+                    node.metadata is None
+                    or node.metadata.meta
+                    or node.metadata.version is None
+                ):
+                    continue
+                version = agreed.setdefault(node.key, node.metadata.version)
+                assert (
+                    version == node.metadata.version
+                ), f"{target.name} resolved {node.key} to {node.metadata.version}, not {version}"
+
+        if not rejections:
+            return results
+
+    # Every pass rejected a version, so there is a last rejection to report.
+    assert last is not None
+    LOG.error(
+        "The solutions still disagree after %d passes. REQ_COMPILE_MAX_GROUP_PASSES "
+        "raises the limit.",
+        max_passes,
+    )
+    raise NoCommonVersionException(last.cause.name, rejected[last.cause.name])
+
+
 def _add_constraints(
     all_pinned: bool,
     constraint_reqs: Optional[Iterable[RequirementContainer]],

req_compile-1.4.0/req_compile/errors.py

@@ -0,0 +1,134 @@
+"""Errors describing problems that can occur when extracting metadata"""
+
+from typing import TYPE_CHECKING, Any, List, NamedTuple, Optional
+
+import packaging.requirements
+import packaging.version
+
+from req_compile.utils import NormName
+
+if TYPE_CHECKING:
+    from req_compile.dists import DependencyNode
+    from req_compile.target import TargetEnvironment
+
+
+class ExceptionWithDetails(Exception):
+    def __init__(self) -> None:
+        super(ExceptionWithDetails, self).__init__()
+        self.results: Optional[Any] = None
+
+
+class MetadataError(ExceptionWithDetails):
+    def __init__(
+        self, name: str, version: Optional[packaging.version.Version], ex: Exception
+    ) -> None:
+        super(MetadataError, self).__init__()
+        self.name = name
+        self.version = version
+        self.ex = ex
+
+    def __str__(self) -> str:
+        return "Failed to parse metadata for package {} ({}) - {}: {}".format(
+            self.name, self.version, self.ex.__class__.__name__, str(self.ex)
+        )
+
+
+class NoCandidateException(ExceptionWithDetails):
+    def __init__(
+        self, req: packaging.requirements.Requirement, results: Any = None
+    ) -> None:
+        super(NoCandidateException, self).__init__()
+        self.req = req
+        self.results = results
+        self.check_level = 0
+        # List of versions marked do not use because they produce conflicts with other deps.
+        self.do_not_use: list[packaging.version.Version] = []
+        # Node that conflicted with this req, if applicable.
+        self.conflicting_node: Optional["DependencyNode"] = None
+        # Project name that was walked back, if applicable.
+        self.walkback_project: Optional[str] = None
+
+    def __str__(self) -> str:
+        if self.req.specifier:
+            return 'NoCandidateException - no candidate for "{}" satisfies {}'.format(
+                self.req.name, self.req.specifier
+            )
+        return 'NoCandidateException - no candidates found for "{}"'.format(
+            self.req.name
+        )
+
+
+class PinConflictException(NoCandidateException):
+    """A soft pin could not be honored for a requirement that is otherwise solvable.
+
+    Raised in place of `NoCandidateException` when the requirement without the
+    pin can be satisfied, so the caller can lift the pin and resolve again. See
+    `CompileOptions.soft_pins`.
+    """
+
+    def __init__(
+        self,
+        name: NormName,
+        pin: packaging.requirements.Requirement,
+        req: packaging.requirements.Requirement,
+        node: "DependencyNode",
+        no_candidate: bool,
+    ) -> None:
+        """
+        Args:
+            name: The normalized name of the pinned project.
+            pin: The soft pin that could not be honored.
+            req: The requirement without the pin, as the reverse dependencies and
+                hard pins constrain it.
+            node: The node the pin applies to.
+            no_candidate: True when the pin conflicts with nothing but no candidate
+                satisfies it, e.g. the pinned version has no artifact for the
+                target. False when the pin conflicts with `req`.
+        """
+        super().__init__(req)
+        self.name = name
+        self.pin = pin
+        self.node = node
+        self.no_candidate = no_candidate
+
+    def __str__(self) -> str:
+        if self.no_candidate:
+            return f"no candidate for {self.pin}"
+        return f"{self.pin} conflicts with {self.req}"
+
+
+class Rejection(NamedTuple):
+    """A version of a project that one of the solutions compiled together cannot use."""
+
+    target: "TargetEnvironment"
+    # The version the other solutions had agreed on, or None if none had and the
+    # target cannot use any version left after the earlier rejections.
+    version: Optional[packaging.version.Version]
+    cause: PinConflictException
+
+
+class NoCommonVersionException(ExceptionWithDetails):
+    """Solutions compiled together cannot agree on the version of a project."""
+
+    def __init__(self, name: NormName, rejections: List[Rejection]) -> None:
+        """
+        Args:
+            name: The normalized name of the project.
+            rejections: The versions some target could not use, in the order they
+                were rejected, ending with the failure that stopped the search.
+        """
+        super().__init__()
+        self.name = name
+        self.rejections = list(rejections)
+
+    def __str__(self) -> str:
+        lines = [f"No version of {self.name} can be used by every solution:"]
+        for rejection in self.rejections:
+            if rejection.version is None:
+                lines.append(f"  {rejection.target.name}: {rejection.cause}")
+            else:
+                lines.append(
+                    f"  {rejection.target.name} cannot use "
+                    f"{self.name}=={rejection.version}: {rejection.cause}"
+                )
+        return "\n".join(lines)