Add support for PEP 440 version specifiers in the --python flag. (#3008)

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

Author: rahuldevikar

docs/changelog/2994.feature.rst

@@ -0,0 +1 @@
+Add support for PEP 440 version specifiers in the ``--python`` flag. Users can now specify Python versions using operators like ``>=``, ``<=``, ``~=``, etc. For example: ``virtualenv --python=">=3.12" myenv`` `.

docs/cli_interface.rst

@@ -38,6 +38,7 @@ To avoid confusion, it's best to think of them as the "rule" and the "hint".
 This flag sets the mandatory requirements for the interpreter. The ``<spec>`` can be:
 
 - **A version string** (e.g., ``python3.8``, ``pypy3``). ``virtualenv`` will search for any interpreter that matches this version.
+- **A version specifier** using PEP 440 operators (e.g., ``>=3.12``, ``~=3.11.0``, ``python>=3.10``). ``virtualenv`` will search for any interpreter that satisfies the version constraint. You can also specify the implementation: ``cpython>=3.12``.
 - **An absolute path** (e.g., ``/usr/bin/python3.8``). This is a *strict* requirement. Only the interpreter at this exact path will be used. If it does not exist or is not a valid interpreter, creation will fail.
 
 **``--try-first-with <path>``: The Hint**

src/virtualenv/discovery/builtin.py

@@ -46,8 +46,9 @@ def add_parser_arguments(cls, parser: ArgumentParser) -> None:
             type=str,
             action="append",
             default=[],
-            help="interpreter based on what to create environment (path/identifier) "
-            "- by default use the interpreter where the tool is installed - first found wins",
+            help="interpreter based on what to create environment (path/identifier/version-specifier) "
+            "- by default use the interpreter where the tool is installed - first found wins. "
+            "Version specifiers (e.g., >=3.12, ~=3.11.0, ==3.10) are also supported",
         )
         parser.add_argument(
             "--try-first-with",

src/virtualenv/discovery/py_info.py

@@ -393,7 +393,7 @@ def clear_cache(cls, app_data):
         clear(app_data)
         cls._cache_exe_discovery.clear()
 
-    def satisfies(self, spec, impl_must_match):  # noqa: C901, PLR0911
+    def satisfies(self, spec, impl_must_match):  # noqa: C901, PLR0911, PLR0912
         """Check if a given specification can be satisfied by the this python interpreter instance."""
         if spec.path:
             if self.executable == os.path.abspath(spec.path):
@@ -422,6 +422,20 @@ def satisfies(self, spec, impl_must_match):  # noqa: C901, PLR0911
         if spec.free_threaded is not None and spec.free_threaded != self.free_threaded:
             return False
 
+        if spec.version_specifier is not None:
+            version_info = self.version_info
+            release = f"{version_info.major}.{version_info.minor}.{version_info.micro}"
+            if version_info.releaselevel != "final":
+                suffix = {
+                    "alpha": "a",
+                    "beta": "b",
+                    "candidate": "rc",
+                }.get(version_info.releaselevel)
+                if suffix is not None:
+                    release = f"{release}{suffix}{version_info.serial}"
+            if not spec.version_specifier.contains(release):
+                return False
+
         for our, req in zip(self.version_info[0:3], (spec.major, spec.minor, spec.micro)):
             if req is not None and our is not None and our != req:
                 return False

src/virtualenv/discovery/py_spec.py

@@ -2,10 +2,14 @@
 
 from __future__ import annotations
 
+import contextlib
 import os
 import re
 
+from virtualenv.util.specifier import SimpleSpecifierSet, SimpleVersion
+
 PATTERN = re.compile(r"^(?P<impl>[a-zA-Z]+)?(?P<version>[0-9.]+)?(?P<threaded>t)?(?:-(?P<arch>32|64))?$")
+SPECIFIER_PATTERN = re.compile(r"^(?:(?P<impl>[A-Za-z]+)\s*)?(?P<spec>(?:===|==|~=|!=|<=|>=|<|>).+)$")
 
 
 class PythonSpec:
@@ -22,6 +26,7 @@ def __init__(  # noqa: PLR0913
         path: str | None,
         *,
         free_threaded: bool | None = None,
+        version_specifier: SpecifierSet | None = None,
     ) -> None:
         self.str_spec = str_spec
         self.implementation = implementation
@@ -31,10 +36,12 @@ def __init__(  # noqa: PLR0913
         self.free_threaded = free_threaded
         self.architecture = architecture
         self.path = path
+        self.version_specifier = version_specifier
 
     @classmethod
     def from_string_spec(cls, string_spec: str):  # noqa: C901, PLR0912
         impl, major, minor, micro, threaded, arch, path = None, None, None, None, None, None, None
+        version_specifier = None
         if os.path.isabs(string_spec):  # noqa: PLR1702
             path = string_spec
         else:
@@ -72,9 +79,41 @@ def _int_or_none(val):
                     arch = _int_or_none(groups["arch"])
 
             if not ok:
+                specifier_match = SPECIFIER_PATTERN.match(string_spec.strip())
+                if specifier_match and SpecifierSet is not None:
+                    impl = specifier_match.group("impl")
+                    spec_text = specifier_match.group("spec").strip()
+                    try:
+                        version_specifier = SpecifierSet(spec_text)
+                    except InvalidSpecifier:
+                        pass
+                    else:
+                        if impl in {"py", "python"}:
+                            impl = None
+                        return cls(
+                            string_spec,
+                            impl,
+                            None,
+                            None,
+                            None,
+                            None,
+                            None,
+                            free_threaded=None,
+                            version_specifier=version_specifier,
+                        )
                 path = string_spec
 
-        return cls(string_spec, impl, major, minor, micro, arch, path, free_threaded=threaded)
+        return cls(
+            string_spec,
+            impl,
+            major,
+            minor,
+            micro,
+            arch,
+            path,
+            free_threaded=threaded,
+            version_specifier=version_specifier,
+        )
 
     def generate_re(self, *, windows: bool) -> re.Pattern:
         """Generate a regular expression for matching against a filename."""
@@ -102,7 +141,36 @@ def generate_re(self, *, windows: bool) -> re.Pattern:
     def is_abs(self):
         return self.path is not None and os.path.isabs(self.path)
 
-    def satisfies(self, spec):
+    def _check_version_specifier(self, spec):
+        """Check if version specifier is satisfied."""
+        components: list[int] = []
+        for part in (self.major, self.minor, self.micro):
+            if part is None:
+                break
+            components.append(part)
+        if not components:
+            return True
+
+        version_str = ".".join(str(part) for part in components)
+        with contextlib.suppress(InvalidVersion):
+            Version(version_str)
+            for item in spec.version_specifier:
+                # Check precision requirements
+                required_precision = self._get_required_precision(item)
+                if required_precision is None or len(components) < required_precision:
+                    continue
+                if not item.contains(version_str):
+                    return False
+        return True
+
+    @staticmethod
+    def _get_required_precision(item):
+        """Get the required precision for a specifier item."""
+        with contextlib.suppress(AttributeError, ValueError):
+            return len(item.version.release)
+        return None
+
+    def satisfies(self, spec):  # noqa: PLR0911
         """Called when there's a candidate metadata spec to see if compatible - e.g. PEP-514 on Windows."""
         if spec.is_abs and self.is_abs and self.path != spec.path:
             return False
@@ -113,17 +181,39 @@ def satisfies(self, spec):
         if spec.free_threaded is not None and spec.free_threaded != self.free_threaded:
             return False
 
+        if spec.version_specifier is not None and not self._check_version_specifier(spec):
+            return False
+
         for our, req in zip((self.major, self.minor, self.micro), (spec.major, spec.minor, spec.micro)):
             if req is not None and our is not None and our != req:
                 return False
         return True
 
     def __repr__(self) -> str:
         name = type(self).__name__
-        params = "implementation", "major", "minor", "micro", "architecture", "path", "free_threaded"
+        params = (
+            "implementation",
+            "major",
+            "minor",
+            "micro",
+            "architecture",
+            "path",
+            "free_threaded",
+            "version_specifier",
+        )
         return f"{name}({', '.join(f'{k}={getattr(self, k)}' for k in params if getattr(self, k) is not None)})"
 
 
+# Create aliases for backward compatibility
+SpecifierSet = SimpleSpecifierSet
+Version = SimpleVersion
+InvalidSpecifier = ValueError
+InvalidVersion = ValueError
+
 __all__ = [
+    "InvalidSpecifier",
+    "InvalidVersion",
     "PythonSpec",
+    "SpecifierSet",
+    "Version",
 ]