feat(constraints): support <0 specifier to block packages

The convention `<0` (also `<0.0` and `<0.0.0`) is intentionally
unsatisfiable and used to exclude a package from builds. Skip the
`is_unsatisfiable()` rejection for these specifiers and add a
`Constraints.is_blocked()` query method. Combining a blocked and a
non-blocked constraint for the same package raises an error.

Co-Authored-By: Claude <claude@anthropic.com>

Author: tiran

docs/how-tos/bootstrap-constraints.rst

@@ -35,3 +35,18 @@ production packages.
 
 This will use the constraints in the ``constraints.txt`` file to build the
 production packages for ``my-package``.
+
+Blocking packages
+-----------------
+
+To block a package entirely so that no version is accepted, use the special
+constraint ``<0`` (or equivalently ``<0.0`` or ``<0.0.0``). No valid Python
+version can satisfy this specifier, so the package is effectively excluded from
+the build.
+
+.. code-block:: text
+
+   unwanted-package<0
+
+A blocked constraint cannot be combined with a regular constraint for the same
+package. Adding both will raise an error.

src/fromager/constraints.py

@@ -3,14 +3,28 @@
 from collections.abc import Generator
 
 from packaging.requirements import Requirement
+from packaging.specifiers import SpecifierSet
 from packaging.utils import NormalizedName, canonicalize_name
 from packaging.version import Version
 
 from . import requirements_file
 
+#: Specifiers that block a package entirely (no version can satisfy them).
+#: Used as a convention to exclude packages from builds.
+_BLOCKED_SPECIFIERS: frozenset[str] = frozenset({"<0", "<0.0", "<0.0.0"})
+
 logger = logging.getLogger(__name__)
 
 
+def _is_blocked_specifier(specifier: SpecifierSet) -> bool:
+    """Return True if specifier blocks a package entirely.
+
+    The convention ``<0``, ``<0.0``, or ``<0.0.0`` is used to mark a
+    package as blocked so that no version can satisfy the constraint.
+    """
+    return str(specifier) in _BLOCKED_SPECIFIERS
+
+
 class InvalidConstraintError(ValueError):
     pass
 
@@ -47,23 +61,34 @@ def add_constraint(self, unparsed: str) -> None:
         if not req.specifier:
             raise InvalidConstraintError(f"Constraint {unparsed!r} has no specifiers")
 
+        # A "blocked" specifier (<0, <0.0, <0.0.0) is intentionally
+        # unsatisfiable and used to exclude a package from builds.
+        blocked = _is_blocked_specifier(req.specifier)
+
         # verify that incoming constraint is okay by itself
-        if req.specifier.is_unsatisfiable():
+        if not blocked and req.specifier.is_unsatisfiable():
             raise InvalidConstraintError(f"Constraint {unparsed!r} is unsatisfiable")
 
         if not requirements_file.evaluate_marker(req, req):
             logger.debug(f"Constraint {req} does not match environment")
             return
 
         if previous is not None:
-            logger.debug("combining constraints %s and %s", previous, req)
-            new_specifier = req.specifier & previous.specifier
-            if new_specifier.is_unsatisfiable():
+            prev_blocked = _is_blocked_specifier(previous.specifier)
+            if blocked != prev_blocked:
                 raise InvalidConstraintError(
-                    f"Combined specifier '{new_specifier}' is not satisfiable "
+                    f"Cannot combine blocked and non-blocked constraints "
                     f"(existing: {previous}, new: {req})"
                 )
-            req.specifier = new_specifier
+            if not blocked:
+                logger.debug("combining constraints %s and %s", previous, req)
+                new_specifier = req.specifier & previous.specifier
+                if new_specifier.is_unsatisfiable():
+                    raise InvalidConstraintError(
+                        f"Combined specifier '{new_specifier}' is not satisfiable "
+                        f"(existing: {previous}, new: {req})"
+                    )
+                req.specifier = new_specifier
         else:
             logger.debug(f"adding constraint {req}")
 
@@ -85,6 +110,13 @@ def allow_prerelease(self, pkg_name: str) -> bool:
             return bool(constraint.specifier.prereleases)
         return False
 
+    def is_blocked(self, pkg_name: str) -> bool:
+        """Return True if the package is blocked by a ``<0`` constraint."""
+        constraint = self.get_constraint(pkg_name)
+        if constraint:
+            return _is_blocked_specifier(constraint.specifier)
+        return False
+
     def is_satisfied_by(self, pkg_name: str, version: Version) -> bool:
         constraint = self.get_constraint(pkg_name)
         if constraint:

tests/test_constraints.py

@@ -140,3 +140,32 @@ def test_combine_constraints() -> None:
     assert c.get_constraint("foo") == Requirement("foo<2.0,>=1.0")
     c.add_constraint("foo!=1.1.0")
     assert c.get_constraint("foo") == Requirement("foo<2.0,>=1.0,!=1.1.0")
+
+
+@pytest.mark.parametrize("specifier", ["<0", "<0.0", "<0.0.0"])
+def test_blocked_package(specifier: str) -> None:
+    c = Constraints()
+    c.add_constraint(f"blocked-pkg{specifier}")
+    assert c.is_blocked("blocked-pkg")
+    assert not c.is_satisfied_by("blocked-pkg", Version("0"))
+    assert not c.is_satisfied_by("blocked-pkg", Version("0.0.1"))
+    assert not c.is_satisfied_by("blocked-pkg", Version("1.0"))
+
+
+def test_blocked_then_non_blocked_raises() -> None:
+    c = Constraints()
+    c.add_constraint("foo<0")
+    with pytest.raises(InvalidConstraintError, match=r"blocked and non-blocked"):
+        c.add_constraint("foo>=1.0")
+
+
+def test_non_blocked_then_blocked_raises() -> None:
+    c = Constraints()
+    c.add_constraint("foo>=1.0")
+    with pytest.raises(InvalidConstraintError, match=r"blocked and non-blocked"):
+        c.add_constraint("foo<0")
+
+
+def test_is_blocked_unknown_package() -> None:
+    c = Constraints()
+    assert not c.is_blocked("unknown")