Inline dependency-versions syntax (#2122)

* Write docs for inline dependency-versions

* Change the `inline` keyword to `packages` for better readability

* Implement inline package constraints

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Add schema for TOML properties

* Change the parsing of the option to parse filenames as-is

* Add a unit test for table-parsing of the option

* Remove unneeded shlex.quote on the dependency-version test

* Tidy-ups, comments, docs fixes

* Add test for empty packages option value

* Fix empty packages scenario

And, remove some optionals to reduce the problem space

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

cibuildwheel/util/packaging.py

@@ -1,4 +1,6 @@
+import shlex
 from collections.abc import Mapping, MutableMapping, Sequence
+from dataclasses import dataclass, field
 from pathlib import Path, PurePath
 from typing import Any, Literal, Self, TypeVar
 
@@ -6,47 +8,109 @@ from packaging.utils import parse_wheel_filename
 
 from . import resources
 from .cmd import call
+from .helpers import parse_key_value_string, unwrap
 
 
+@dataclass()
 class DependencyConstraints:
-    def __init__(self, base_file_path: Path):
-        assert base_file_path.exists()
-        self.base_file_path = base_file_path.resolve()
+    base_file_path: Path | None = None
+    packages: list[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if self.packages and self.base_file_path is not None:
+            msg = "Cannot specify both a file and packages in the dependency constraints"
+            raise ValueError(msg)
+
+        if self.base_file_path is not None:
+            if not self.base_file_path.exists():
+                msg = f"Dependency constraints file not found: {self.base_file_path}"
+                raise FileNotFoundError(msg)
+            self.base_file_path = self.base_file_path.resolve()
 
     @classmethod
-    def with_defaults(cls) -> Self:
+    def pinned(cls) -> Self:
         return cls(base_file_path=resources.CONSTRAINTS)
 
+    @classmethod
+    def latest(cls) -> Self:
+        return cls()
+
+    @classmethod
+    def from_config_string(cls, config_string: str) -> Self:
+        if config_string == "pinned":
+            return cls.pinned()
+
+        if config_string == "latest" or not config_string:
+            return cls.latest()
+
+        if config_string.startswith(("file:", "packages:")):
+            # we only do the table-style parsing if it looks like a table,
+            # because this option used to be only a file path. We don't want
+            # to break existing configurations, whose file paths might include
+            # special characters like ':' or ' ', which would require quoting
+            # if they were to be passed as a parse_key_value_string positional
+            # argument.
+            return cls.from_table_style_config_string(config_string)
+
+        return cls(base_file_path=Path(config_string))
+
+    @classmethod
+    def from_table_style_config_string(cls, config_string: str) -> Self:
+        config_dict = parse_key_value_string(config_string, kw_arg_names=["file", "packages"])
+        files = config_dict.get("file")
+        packages = config_dict.get("packages") or []
+
+        if files and packages:
+            msg = "Cannot specify both a file and packages in dependency-versions"
+            raise ValueError(msg)
+
+        if files:
+            if len(files) > 1:
+                msg = unwrap("""
+                    Only one file can be specified in dependency-versions.
+                    If you intended to pass only one, perhaps you need to quote the path?
+                """)
+                raise ValueError(msg)
+
+            return cls(base_file_path=Path(files[0]))
+
+        return cls(packages=packages)
+
     def get_for_python_version(
-        self, version: str, *, variant: Literal["python", "pyodide"] = "python"
-    ) -> Path:
-        version_parts = version.split(".")
+        self, *, version: str, variant: Literal["python", "pyodide"] = "python", tmp_dir: Path
+    ) -> Path | None:
+        if self.packages:
+            constraint_file = tmp_dir / "constraints.txt"
+            constraint_file.write_text("\n".join(self.packages))
+            return constraint_file
 
-        # try to find a version-specific dependency file e.g. if
-        # ./constraints.txt is the base, look for ./constraints-python36.txt
-        specific_stem = self.base_file_path.stem + f"-{variant}{version_parts[0]}{version_parts[1]}"
-        specific_name = specific_stem + self.base_file_path.suffix
-        specific_file_path = self.base_file_path.with_name(specific_name)
+        if self.base_file_path is not None:
+            version_parts = version.split(".")
 
-        if specific_file_path.exists():
-            return specific_file_path
-        else:
-            return self.base_file_path
+            # try to find a version-specific dependency file e.g. if
+            # ./constraints.txt is the base, look for ./constraints-python36.txt
+            specific_stem = (
+                self.base_file_path.stem + f"-{variant}{version_parts[0]}{version_parts[1]}"
+            )
+            specific_name = specific_stem + self.base_file_path.suffix
+            specific_file_path = self.base_file_path.with_name(specific_name)
 
-    def __repr__(self) -> str:
-        return f"{self.__class__.__name__}({self.base_file_path!r})"
+            if specific_file_path.exists():
+                return specific_file_path
+            else:
+                return self.base_file_path
 
-    def __eq__(self, o: object) -> bool:
-        if not isinstance(o, DependencyConstraints):
-            return False
-
-        return self.base_file_path == o.base_file_path
+        return None
 
     def options_summary(self) -> Any:
-        if self == DependencyConstraints.with_defaults():
+        if self == DependencyConstraints.pinned():
             return "pinned"
-        else:
+        elif self.packages:
+            return {"packages": " ".join(shlex.quote(p) for p in self.packages)}
+        elif self.base_file_path is not None:
             return self.base_file_path.name
+        else:
+            return "latest"
 
 
 def get_pip_version(env: Mapping[str, str]) -> str: