pip 25.3__py3-none-any.whl → 26.0__py3-none-any.whl

pip/_vendor/packaging/specifiers.py

@@ -13,22 +13,33 @@ from __future__ import annotations
 import abc
 import itertools
 import re
-from typing import Callable, Iterable, Iterator, TypeVar, Union
+from typing import Callable, Final, Iterable, Iterator, TypeVar, Union
 
 from .utils import canonicalize_version
-from .version import Version
+from .version import InvalidVersion, Version
 
 UnparsedVersion = Union[Version, str]
 UnparsedVersionVar = TypeVar("UnparsedVersionVar", bound=UnparsedVersion)
 CallableOperator = Callable[[Version, str], bool]
 
 
-def _coerce_version(version: UnparsedVersion) -> Version:
+def _coerce_version(version: UnparsedVersion) -> Version | None:
     if not isinstance(version, Version):
-        version = Version(version)
+        try:
+            version = Version(version)
+        except InvalidVersion:
+            return None
     return version
 
 
+def _public_version(version: Version) -> Version:
+    return version.__replace__(local=None)
+
+
+def _base_version(version: Version) -> Version:
+    return version.__replace__(pre=None, post=None, dev=None, local=None)
+
+
 class InvalidSpecifier(ValueError):
     """
     Raised when attempting to create a :class:`Specifier` with a specifier
@@ -42,6 +53,14 @@ class InvalidSpecifier(ValueError):
 
 
 class BaseSpecifier(metaclass=abc.ABCMeta):
+    __slots__ = ()
+    __match_args__ = ("_str",)
+
+    @property
+    def _str(self) -> str:
+        """Internal property for match_args"""
+        return str(self)
+
     @abc.abstractmethod
     def __str__(self) -> str:
         """
@@ -73,7 +92,7 @@ class BaseSpecifier(metaclass=abc.ABCMeta):
         prereleases or it can be set to ``None`` (the default) to use default semantics.
         """
 
-    @prereleases.setter
+    @prereleases.setter  # noqa: B027
     def prereleases(self, value: bool) -> None:
         """Setter for :attr:`prereleases`.
 
@@ -106,6 +125,8 @@ class Specifier(BaseSpecifier):
         comma-separated version specifiers (which is what package metadata contains).
     """
 
+    __slots__ = ("_prereleases", "_spec", "_spec_version")
+
     _operator_regex_str = r"""
         (?P<operator>(~=|==|!=|<=|>=|<|>|===))
         """
@@ -204,11 +225,11 @@ class Specifier(BaseSpecifier):
         """
 
     _regex = re.compile(
-        r"^\s*" + _operator_regex_str + _version_regex_str + r"\s*$",
+        r"\s*" + _operator_regex_str + _version_regex_str + r"\s*",
         re.VERBOSE | re.IGNORECASE,
     )
 
-    _operators = {
+    _operators: Final = {
         "~=": "compatible",
         "==": "equal",
         "!=": "not_equal",
@@ -232,7 +253,7 @@ class Specifier(BaseSpecifier):
         :raises InvalidSpecifier:
             If the given specifier is invalid (i.e. bad syntax).
         """
-        match = self._regex.search(spec)
+        match = self._regex.fullmatch(spec)
         if not match:
             raise InvalidSpecifier(f"Invalid specifier: {spec!r}")
 
@@ -244,33 +265,62 @@ class Specifier(BaseSpecifier):
         # Store whether or not this Specifier should accept prereleases
         self._prereleases = prereleases
 
-    # https://github.com/python/mypy/pull/13475#pullrequestreview-1079784515
-    @property  # type: ignore[override]
-    def prereleases(self) -> bool:
+        # Specifier version cache
+        self._spec_version: tuple[str, Version] | None = None
+
+    def _get_spec_version(self, version: str) -> Version | None:
+        """One element cache, as only one spec Version is needed per Specifier."""
+        if self._spec_version is not None and self._spec_version[0] == version:
+            return self._spec_version[1]
+
+        version_specifier = _coerce_version(version)
+        if version_specifier is None:
+            return None
+
+        self._spec_version = (version, version_specifier)
+        return version_specifier
+
+    def _require_spec_version(self, version: str) -> Version:
+        """Get spec version, asserting it's valid (not for === operator).
+
+        This method should only be called for operators where version
+        strings are guaranteed to be valid PEP 440 versions (not ===).
+        """
+        spec_version = self._get_spec_version(version)
+        assert spec_version is not None
+        return spec_version
+
+    @property
+    def prereleases(self) -> bool | None:
         # If there is an explicit prereleases set for this, then we'll just
         # blindly use that.
         if self._prereleases is not None:
             return self._prereleases
 
-        # Look at all of our specifiers and determine if they are inclusive
-        # operators, and if they are if they are including an explicit
-        # prerelease.
-        operator, version = self._spec
-        if operator in ["==", ">=", "<=", "~=", "===", ">", "<"]:
-            # The == specifier can include a trailing .*, if it does we
-            # want to remove before parsing.
-            if operator == "==" and version.endswith(".*"):
-                version = version[:-2]
-
-            # Parse the version, and if it is a pre-release than this
-            # specifier allows pre-releases.
-            if Version(version).is_prerelease:
+        # Only the "!=" operator does not imply prereleases when
+        # the version in the specifier is a prerelease.
+        operator, version_str = self._spec
+        if operator != "!=":
+            # The == specifier with trailing .* cannot include prereleases
+            # e.g. "==1.0a1.*" is not valid.
+            if operator == "==" and version_str.endswith(".*"):
+                return False
+
+            # "===" can have arbitrary string versions, so we cannot parse
+            # those, we take prereleases as unknown (None) for those.
+            version = self._get_spec_version(version_str)
+            if version is None:
+                return None
+
+            # For all other operators, use the check if spec Version
+            # object implies pre-releases.
+            if version.is_prerelease:
                 return True
 
         return False
 
     @prereleases.setter
-    def prereleases(self, value: bool) -> None:
+    def prereleases(self, value: bool | None) -> None:
         self._prereleases = value
 
     @property
@@ -321,11 +371,17 @@ class Specifier(BaseSpecifier):
 
     @property
     def _canonical_spec(self) -> tuple[str, str]:
+        operator, version = self._spec
+        if operator == "===" or version.endswith(".*"):
+            return operator, version
+
+        spec_version = self._require_spec_version(version)
+
         canonical_version = canonicalize_version(
-            self._spec[1],
-            strip_trailing_zero=(self._spec[0] != "~="),
+            spec_version, strip_trailing_zero=(operator != "~=")
         )
-        return self._spec[0], canonical_version
+
+        return operator, canonical_version
 
     def __hash__(self) -> int:
         return hash(self._canonical_spec)
@@ -390,7 +446,7 @@ class Specifier(BaseSpecifier):
         if spec.endswith(".*"):
             # In the case of prefix matching we want to ignore local segment.
             normalized_prospective = canonicalize_version(
-                prospective.public, strip_trailing_zero=False
+                _public_version(prospective), strip_trailing_zero=False
             )
             # Get the normalized version string ignoring the trailing .*
             normalized_spec = canonicalize_version(spec[:-2], strip_trailing_zero=False)
@@ -415,13 +471,13 @@ class Specifier(BaseSpecifier):
             return shortened_prospective == split_spec
         else:
             # Convert our spec string into a Version
-            spec_version = Version(spec)
+            spec_version = self._require_spec_version(spec)
 
             # If the specifier does not have a local segment, then we want to
             # act as if the prospective version also does not have a local
             # segment.
             if not spec_version.local:
-                prospective = Version(prospective.public)
+                prospective = _public_version(prospective)
 
             return prospective == spec_version
 
@@ -432,18 +488,18 @@ class Specifier(BaseSpecifier):
         # NB: Local version identifiers are NOT permitted in the version
         # specifier, so local version labels can be universally removed from
         # the prospective version.
-        return Version(prospective.public) <= Version(spec)
+        return _public_version(prospective) <= self._require_spec_version(spec)
 
     def _compare_greater_than_equal(self, prospective: Version, spec: str) -> bool:
         # NB: Local version identifiers are NOT permitted in the version
         # specifier, so local version labels can be universally removed from
         # the prospective version.
-        return Version(prospective.public) >= Version(spec)
+        return _public_version(prospective) >= self._require_spec_version(spec)
 
     def _compare_less_than(self, prospective: Version, spec_str: str) -> bool:
         # Convert our spec to a Version instance, since we'll want to work with
         # it as a version.
-        spec = Version(spec_str)
+        spec = self._require_spec_version(spec_str)
 
         # Check to see if the prospective version is less than the spec
         # version. If it's not we can short circuit and just return False now
@@ -455,9 +511,12 @@ class Specifier(BaseSpecifier):
         # includes is a pre-release version, that we do not accept pre-release
         # versions for the version mentioned in the specifier (e.g. <3.1 should
         # not match 3.1.dev0, but should match 3.0.dev0).
-        if not spec.is_prerelease and prospective.is_prerelease:
-            if Version(prospective.base_version) == Version(spec.base_version):
-                return False
+        if (
+            not spec.is_prerelease
+            and prospective.is_prerelease
+            and _base_version(prospective) == _base_version(spec)
+        ):
+            return False
 
         # If we've gotten to here, it means that prospective version is both
         # less than the spec version *and* it's not a pre-release of the same
@@ -467,7 +526,7 @@ class Specifier(BaseSpecifier):
     def _compare_greater_than(self, prospective: Version, spec_str: str) -> bool:
         # Convert our spec to a Version instance, since we'll want to work with
         # it as a version.
-        spec = Version(spec_str)
+        spec = self._require_spec_version(spec_str)
 
         # Check to see if the prospective version is greater than the spec
         # version. If it's not we can short circuit and just return False now
@@ -479,22 +538,26 @@ class Specifier(BaseSpecifier):
         # includes is a post-release version, that we do not accept
         # post-release versions for the version mentioned in the specifier
         # (e.g. >3.1 should not match 3.0.post0, but should match 3.2.post0).
-        if not spec.is_postrelease and prospective.is_postrelease:
-            if Version(prospective.base_version) == Version(spec.base_version):
-                return False
+        if (
+            not spec.is_postrelease
+            and prospective.is_postrelease
+            and _base_version(prospective) == _base_version(spec)
+        ):
+            return False
 
         # Ensure that we do not allow a local version of the version mentioned
         # in the specifier, which is technically greater than, to match.
-        if prospective.local is not None:
-            if Version(prospective.base_version) == Version(spec.base_version):
-                return False
+        if prospective.local is not None and _base_version(
+            prospective
+        ) == _base_version(spec):
+            return False
 
         # If we've gotten to here, it means that prospective version is both
         # greater than the spec version *and* it's not a pre-release of the
         # same version in the spec.
         return True
 
-    def _compare_arbitrary(self, prospective: Version, spec: str) -> bool:
+    def _compare_arbitrary(self, prospective: Version | str, spec: str) -> bool:
         return str(prospective).lower() == str(spec).lower()
 
     def __contains__(self, item: str | Version) -> bool:
@@ -512,7 +575,7 @@ class Specifier(BaseSpecifier):
         >>> "1.0.0" in Specifier(">=1.2.3")
         False
         >>> "1.3.0a1" in Specifier(">=1.2.3")
-        False
+        True
         >>> "1.3.0a1" in Specifier(">=1.2.3", prereleases=True)
         True
         """
@@ -526,8 +589,8 @@ class Specifier(BaseSpecifier):
             :class:`Version` instance.
         :param prereleases:
             Whether or not to match prereleases with this Specifier. If set to
-            ``None`` (the default), it uses :attr:`prereleases` to determine
-            whether or not prereleases are allowed.
+            ``None`` (the default), it will follow the recommendation from
+            :pep:`440` and match prereleases, as there are no other versions.
 
         >>> Specifier(">=1.2.3").contains("1.2.3")
         True
@@ -536,31 +599,14 @@ class Specifier(BaseSpecifier):
         >>> Specifier(">=1.2.3").contains("1.0.0")
         False
         >>> Specifier(">=1.2.3").contains("1.3.0a1")
-        False
-        >>> Specifier(">=1.2.3", prereleases=True).contains("1.3.0a1")
         True
-        >>> Specifier(">=1.2.3").contains("1.3.0a1", prereleases=True)
+        >>> Specifier(">=1.2.3", prereleases=False).contains("1.3.0a1")
+        False
+        >>> Specifier(">=1.2.3").contains("1.3.0a1")
         True
         """
 
-        # Determine if prereleases are to be allowed or not.
-        if prereleases is None:
-            prereleases = self.prereleases
-
-        # Normalize item to a Version, this allows us to have a shortcut for
-        # "2.0" in Specifier(">=2")
-        normalized_item = _coerce_version(item)
-
-        # Determine if we should be supporting prereleases in this specifier
-        # or not, if we do not support prereleases than we can short circuit
-        # logic if this version is a prereleases.
-        if normalized_item.is_prerelease and not prereleases:
-            return False
-
-        # Actually do the comparison to determine if this item is contained
-        # within this Specifier or not.
-        operator_callable: CallableOperator = self._get_operator(self.operator)
-        return operator_callable(normalized_item, self.version)
+        return bool(list(self.filter([item], prereleases=prereleases)))
 
     def filter(
         self, iterable: Iterable[UnparsedVersionVar], prereleases: bool | None = None
@@ -572,13 +618,8 @@ class Specifier(BaseSpecifier):
             The items in the iterable will be filtered according to the specifier.
         :param prereleases:
             Whether or not to allow prereleases in the returned iterator. If set to
-            ``None`` (the default), it will be intelligently decide whether to allow
-            prereleases or not (based on the :attr:`prereleases` attribute, and
-            whether the only versions matching are prereleases).
-
-        This method is smarter than just ``filter(Specifier().contains, [...])``
-        because it implements the rule from :pep:`440` that a prerelease item
-        SHOULD be accepted if no other versions match the given specifier.
+            ``None`` (the default), it will follow the recommendation from :pep:`440`
+            and match prereleases if there are no other versions.
 
         >>> list(Specifier(">=1.2.3").filter(["1.2", "1.3", "1.5a1"]))
         ['1.3']
@@ -591,40 +632,46 @@ class Specifier(BaseSpecifier):
         >>> list(Specifier(">=1.2.3", prereleases=True).filter(["1.3", "1.5a1"]))
         ['1.3', '1.5a1']
         """
+        prereleases_versions = []
+        found_non_prereleases = False
 
-        yielded = False
-        found_prereleases = []
+        # Determine if to include prereleases by default
+        include_prereleases = (
+            prereleases if prereleases is not None else self.prereleases
+        )
 
-        kw = {"prereleases": prereleases if prereleases is not None else True}
+        # Get the matching operator
+        operator_callable = self._get_operator(self.operator)
 
-        # Attempt to iterate over all the values in the iterable and if any of
-        # them match, yield them.
+        # Filter versions
         for version in iterable:
             parsed_version = _coerce_version(version)
-
-            if self.contains(parsed_version, **kw):
-                # If our version is a prerelease, and we were not set to allow
-                # prereleases, then we'll store it for later in case nothing
-                # else matches this specifier.
-                if parsed_version.is_prerelease and not (
-                    prereleases or self.prereleases
+            if parsed_version is None:
+                # === operator can match arbitrary (non-version) strings
+                if self.operator == "===" and self._compare_arbitrary(
+                    version, self.version
                 ):
-                    found_prereleases.append(version)
-                # Either this is not a prerelease, or we should have been
-                # accepting prereleases from the beginning.
-                else:
-                    yielded = True
                     yield version
+            elif operator_callable(parsed_version, self.version):
+                # If it's not a prerelease or prereleases are allowed, yield it directly
+                if not parsed_version.is_prerelease or include_prereleases:
+                    found_non_prereleases = True
+                    yield version
+                # Otherwise collect prereleases for potential later use
+                elif prereleases is None and self._prereleases is not False:
+                    prereleases_versions.append(version)
 
-        # Now that we've iterated over everything, determine if we've yielded
-        # any values, and if we have not and we have any prereleases stored up
-        # then we will go ahead and yield the prereleases.
-        if not yielded and found_prereleases:
-            for version in found_prereleases:
-                yield version
+        # If no non-prereleases were found and prereleases weren't
+        # explicitly forbidden, yield the collected prereleases
+        if (
+            not found_non_prereleases
+            and prereleases is None
+            and self._prereleases is not False
+        ):
+            yield from prereleases_versions
 
 
-_prefix_regex = re.compile(r"^([0-9]+)((?:a|b|c|rc)[0-9]+)$")
+_prefix_regex = re.compile(r"([0-9]+)((?:a|b|c|rc)[0-9]+)")
 
 
 def _version_split(version: str) -> list[str]:
@@ -641,7 +688,7 @@ def _version_split(version: str) -> list[str]:
     result.append(epoch or "0")
 
     for item in rest.split("."):
-        match = _prefix_regex.search(item)
+        match = _prefix_regex.fullmatch(item)
         if match:
             result.extend(match.groups())
         else:
@@ -694,6 +741,8 @@ class SpecifierSet(BaseSpecifier):
     specifiers (``>=3.0,!=3.1``), or no specifier at all.
     """
 
+    __slots__ = ("_prereleases", "_specs")
+
     def __init__(
         self,
         specifiers: str | Iterable[Specifier] = "",
@@ -747,10 +796,13 @@ class SpecifierSet(BaseSpecifier):
 
         # Otherwise we'll see if any of the given specifiers accept
         # prereleases, if any of them do we'll return True, otherwise False.
-        return any(s.prereleases for s in self._specs)
+        if any(s.prereleases for s in self._specs):
+            return True
+
+        return None
 
     @prereleases.setter
-    def prereleases(self, value: bool) -> None:
+    def prereleases(self, value: bool | None) -> None:
         self._prereleases = value
 
     def __repr__(self) -> str:
@@ -810,9 +862,9 @@ class SpecifierSet(BaseSpecifier):
 
         if self._prereleases is None and other._prereleases is not None:
             specifier._prereleases = other._prereleases
-        elif self._prereleases is not None and other._prereleases is None:
-            specifier._prereleases = self._prereleases
-        elif self._prereleases == other._prereleases:
+        elif (
+            self._prereleases is not None and other._prereleases is None
+        ) or self._prereleases == other._prereleases:
             specifier._prereleases = self._prereleases
         else:
             raise ValueError(
@@ -876,7 +928,7 @@ class SpecifierSet(BaseSpecifier):
         >>> "1.0.1" in SpecifierSet(">=1.0.0,!=1.0.1")
         False
         >>> "1.3.0a1" in SpecifierSet(">=1.0.0,!=1.0.1")
-        False
+        True
         >>> "1.3.0a1" in SpecifierSet(">=1.0.0,!=1.0.1", prereleases=True)
         True
         """
@@ -895,8 +947,11 @@ class SpecifierSet(BaseSpecifier):
             :class:`Version` instance.
         :param prereleases:
             Whether or not to match prereleases with this SpecifierSet. If set to
-            ``None`` (the default), it uses :attr:`prereleases` to determine
-            whether or not prereleases are allowed.
+            ``None`` (the default), it will follow the recommendation from :pep:`440`
+            and match prereleases, as there are no other versions.
+        :param installed:
+            Whether or not the item is installed. If set to ``True``, it will
+            accept prerelease versions even if the specifier does not allow them.
 
         >>> SpecifierSet(">=1.0.0,!=1.0.1").contains("1.2.3")
         True
@@ -905,39 +960,19 @@ class SpecifierSet(BaseSpecifier):
         >>> SpecifierSet(">=1.0.0,!=1.0.1").contains("1.0.1")
         False
         >>> SpecifierSet(">=1.0.0,!=1.0.1").contains("1.3.0a1")
-        False
-        >>> SpecifierSet(">=1.0.0,!=1.0.1", prereleases=True).contains("1.3.0a1")
         True
+        >>> SpecifierSet(">=1.0.0,!=1.0.1", prereleases=False).contains("1.3.0a1")
+        False
         >>> SpecifierSet(">=1.0.0,!=1.0.1").contains("1.3.0a1", prereleases=True)
         True
         """
-        # Ensure that our item is a Version instance.
-        if not isinstance(item, Version):
-            item = Version(item)
-
-        # Determine if we're forcing a prerelease or not, if we're not forcing
-        # one for this particular filter call, then we'll use whatever the
-        # SpecifierSet thinks for whether or not we should support prereleases.
-        if prereleases is None:
-            prereleases = self.prereleases
+        version = _coerce_version(item)
 
-        # We can determine if we're going to allow pre-releases by looking to
-        # see if any of the underlying items supports them. If none of them do
-        # and this item is a pre-release then we do not allow it and we can
-        # short circuit that here.
-        # Note: This means that 1.0.dev1 would not be contained in something
-        #       like >=1.0.devabc however it would be in >=1.0.debabc,>0.0.dev0
-        if not prereleases and item.is_prerelease:
-            return False
-
-        if installed and item.is_prerelease:
-            item = Version(item.base_version)
+        if version is not None and installed and version.is_prerelease:
+            prereleases = True
 
-        # We simply dispatch to the underlying specs here to make sure that the
-        # given version is contained within all of them.
-        # Note: This use of all() here means that an empty set of specifiers
-        #       will always return True, this is an explicit design decision.
-        return all(s.contains(item, prereleases=prereleases) for s in self._specs)
+        check_item = item if version is None else version
+        return bool(list(self.filter([check_item], prereleases=prereleases)))
 
     def filter(
         self, iterable: Iterable[UnparsedVersionVar], prereleases: bool | None = None
@@ -949,20 +984,15 @@ class SpecifierSet(BaseSpecifier):
             The items in the iterable will be filtered according to the specifier.
         :param prereleases:
             Whether or not to allow prereleases in the returned iterator. If set to
-            ``None`` (the default), it will be intelligently decide whether to allow
-            prereleases or not (based on the :attr:`prereleases` attribute, and
-            whether the only versions matching are prereleases).
-
-        This method is smarter than just ``filter(SpecifierSet(...).contains, [...])``
-        because it implements the rule from :pep:`440` that a prerelease item
-        SHOULD be accepted if no other versions match the given specifier.
+            ``None`` (the default), it will follow the recommendation from :pep:`440`
+            and match prereleases if there are no other versions.
 
         >>> list(SpecifierSet(">=1.2.3").filter(["1.2", "1.3", "1.5a1"]))
         ['1.3']
         >>> list(SpecifierSet(">=1.2.3").filter(["1.2", "1.3", Version("1.4")]))
         ['1.3', <Version('1.4')>]
         >>> list(SpecifierSet(">=1.2.3").filter(["1.2", "1.5a1"]))
-        []
+        ['1.5a1']
         >>> list(SpecifierSet(">=1.2.3").filter(["1.3", "1.5a1"], prereleases=True))
         ['1.3', '1.5a1']
         >>> list(SpecifierSet(">=1.2.3", prereleases=True).filter(["1.3", "1.5a1"]))
@@ -983,37 +1013,56 @@ class SpecifierSet(BaseSpecifier):
         # Determine if we're forcing a prerelease or not, if we're not forcing
         # one for this particular filter call, then we'll use whatever the
         # SpecifierSet thinks for whether or not we should support prereleases.
-        if prereleases is None:
+        if prereleases is None and self.prereleases is not None:
             prereleases = self.prereleases
 
         # If we have any specifiers, then we want to wrap our iterable in the
         # filter method for each one, this will act as a logical AND amongst
         # each specifier.
         if self._specs:
+            # When prereleases is None, we need to let all versions through
+            # the individual filters, then decide about prereleases at the end
+            # based on whether any non-prereleases matched ALL specs.
             for spec in self._specs:
-                iterable = spec.filter(iterable, prereleases=bool(prereleases))
-            return iter(iterable)
-        # If we do not have any specifiers, then we need to have a rough filter
-        # which will filter out any pre-releases, unless there are no final
-        # releases.
+                iterable = spec.filter(
+                    iterable, prereleases=True if prereleases is None else prereleases
+                )
+
+            if prereleases is not None:
+                # If we have a forced prereleases value,
+                # we can immediately return the iterator.
+                return iter(iterable)
         else:
-            filtered: list[UnparsedVersionVar] = []
-            found_prereleases: list[UnparsedVersionVar] = []
-
-            for item in iterable:
-                parsed_version = _coerce_version(item)
-
-                # Store any item which is a pre-release for later unless we've
-                # already found a final version or we are accepting prereleases
-                if parsed_version.is_prerelease and not prereleases:
-                    if not filtered:
-                        found_prereleases.append(item)
-                else:
-                    filtered.append(item)
-
-            # If we've found no items except for pre-releases, then we'll go
-            # ahead and use the pre-releases
-            if not filtered and found_prereleases and prereleases is None:
-                return iter(found_prereleases)
-
-            return iter(filtered)
+            # Handle empty SpecifierSet cases where prereleases is not None.
+            if prereleases is True:
+                return iter(iterable)
+
+            if prereleases is False:
+                return (
+                    item
+                    for item in iterable
+                    if (version := _coerce_version(item)) is None
+                    or not version.is_prerelease
+                )
+
+        # Finally if prereleases is None, apply PEP 440 logic:
+        # exclude prereleases unless there are no final releases that matched.
+        filtered_items: list[UnparsedVersionVar] = []
+        found_prereleases: list[UnparsedVersionVar] = []
+        found_final_release = False
+
+        for item in iterable:
+            parsed_version = _coerce_version(item)
+            # Arbitrary strings are always included as it is not
+            # possible to determine if they are prereleases,
+            # and they have already passed all specifiers.
+            if parsed_version is None:
+                filtered_items.append(item)
+                found_prereleases.append(item)
+            elif parsed_version.is_prerelease:
+                found_prereleases.append(item)
+            else:
+                filtered_items.append(item)
+                found_final_release = True
+
+        return iter(filtered_items if found_final_release else found_prereleases)