Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/pkg_resources/_vendor/packaging/specifiers.py: 5%
253 statements
« prev ^ index » next coverage.py v7.2.7, created at 2023-06-07 06:35 +0000
1# This file is dual licensed under the terms of the Apache License, Version
2# 2.0, and the BSD License. See the LICENSE file in the root of this repository
3# for complete details.
4"""
5.. testsetup::
7 from packaging.specifiers import Specifier, SpecifierSet, InvalidSpecifier
8 from packaging.version import Version
9"""
11import abc
12import itertools
13import re
14from typing import (
15 Callable,
16 Iterable,
17 Iterator,
18 List,
19 Optional,
20 Set,
21 Tuple,
22 TypeVar,
23 Union,
24)
26from .utils import canonicalize_version
27from .version import Version
29UnparsedVersion = Union[Version, str]
30UnparsedVersionVar = TypeVar("UnparsedVersionVar", bound=UnparsedVersion)
31CallableOperator = Callable[[Version, str], bool]
34def _coerce_version(version: UnparsedVersion) -> Version:
35 if not isinstance(version, Version):
36 version = Version(version)
37 return version
40class InvalidSpecifier(ValueError):
41 """
42 Raised when attempting to create a :class:`Specifier` with a specifier
43 string that is invalid.
45 >>> Specifier("lolwat")
46 Traceback (most recent call last):
47 ...
48 packaging.specifiers.InvalidSpecifier: Invalid specifier: 'lolwat'
49 """
52class BaseSpecifier(metaclass=abc.ABCMeta):
53 @abc.abstractmethod
54 def __str__(self) -> str:
55 """
56 Returns the str representation of this Specifier-like object. This
57 should be representative of the Specifier itself.
58 """
60 @abc.abstractmethod
61 def __hash__(self) -> int:
62 """
63 Returns a hash value for this Specifier-like object.
64 """
66 @abc.abstractmethod
67 def __eq__(self, other: object) -> bool:
68 """
69 Returns a boolean representing whether or not the two Specifier-like
70 objects are equal.
72 :param other: The other object to check against.
73 """
75 @property
76 @abc.abstractmethod
77 def prereleases(self) -> Optional[bool]:
78 """Whether or not pre-releases as a whole are allowed.
80 This can be set to either ``True`` or ``False`` to explicitly enable or disable
81 prereleases or it can be set to ``None`` (the default) to use default semantics.
82 """
84 @prereleases.setter
85 def prereleases(self, value: bool) -> None:
86 """Setter for :attr:`prereleases`.
88 :param value: The value to set.
89 """
91 @abc.abstractmethod
92 def contains(self, item: str, prereleases: Optional[bool] = None) -> bool:
93 """
94 Determines if the given item is contained within this specifier.
95 """
97 @abc.abstractmethod
98 def filter(
99 self, iterable: Iterable[UnparsedVersionVar], prereleases: Optional[bool] = None
100 ) -> Iterator[UnparsedVersionVar]:
101 """
102 Takes an iterable of items and filters them so that only items which
103 are contained within this specifier are allowed in it.
104 """
107class Specifier(BaseSpecifier):
108 """This class abstracts handling of version specifiers.
110 .. tip::
112 It is generally not required to instantiate this manually. You should instead
113 prefer to work with :class:`SpecifierSet` instead, which can parse
114 comma-separated version specifiers (which is what package metadata contains).
115 """
117 _operator_regex_str = r"""
118 (?P<operator>(~=|==|!=|<=|>=|<|>|===))
119 """
120 _version_regex_str = r"""
121 (?P<version>
122 (?:
123 # The identity operators allow for an escape hatch that will
124 # do an exact string match of the version you wish to install.
125 # This will not be parsed by PEP 440 and we cannot determine
126 # any semantic meaning from it. This operator is discouraged
127 # but included entirely as an escape hatch.
128 (?<====) # Only match for the identity operator
129 \s*
130 [^\s;)]* # The arbitrary version can be just about anything,
131 # we match everything except for whitespace, a
132 # semi-colon for marker support, and a closing paren
133 # since versions can be enclosed in them.
134 )
135 |
136 (?:
137 # The (non)equality operators allow for wild card and local
138 # versions to be specified so we have to define these two
139 # operators separately to enable that.
140 (?<===|!=) # Only match for equals and not equals
142 \s*
143 v?
144 (?:[0-9]+!)? # epoch
145 [0-9]+(?:\.[0-9]+)* # release
147 # You cannot use a wild card and a pre-release, post-release, a dev or
148 # local version together so group them with a | and make them optional.
149 (?:
150 \.\* # Wild card syntax of .*
151 |
152 (?: # pre release
153 [-_\.]?
154 (alpha|beta|preview|pre|a|b|c|rc)
155 [-_\.]?
156 [0-9]*
157 )?
158 (?: # post release
159 (?:-[0-9]+)|(?:[-_\.]?(post|rev|r)[-_\.]?[0-9]*)
160 )?
161 (?:[-_\.]?dev[-_\.]?[0-9]*)? # dev release
162 (?:\+[a-z0-9]+(?:[-_\.][a-z0-9]+)*)? # local
163 )?
164 )
165 |
166 (?:
167 # The compatible operator requires at least two digits in the
168 # release segment.
169 (?<=~=) # Only match for the compatible operator
171 \s*
172 v?
173 (?:[0-9]+!)? # epoch
174 [0-9]+(?:\.[0-9]+)+ # release (We have a + instead of a *)
175 (?: # pre release
176 [-_\.]?
177 (alpha|beta|preview|pre|a|b|c|rc)
178 [-_\.]?
179 [0-9]*
180 )?
181 (?: # post release
182 (?:-[0-9]+)|(?:[-_\.]?(post|rev|r)[-_\.]?[0-9]*)
183 )?
184 (?:[-_\.]?dev[-_\.]?[0-9]*)? # dev release
185 )
186 |
187 (?:
188 # All other operators only allow a sub set of what the
189 # (non)equality operators do. Specifically they do not allow
190 # local versions to be specified nor do they allow the prefix
191 # matching wild cards.
192 (?<!==|!=|~=) # We have special cases for these
193 # operators so we want to make sure they
194 # don't match here.
196 \s*
197 v?
198 (?:[0-9]+!)? # epoch
199 [0-9]+(?:\.[0-9]+)* # release
200 (?: # pre release
201 [-_\.]?
202 (alpha|beta|preview|pre|a|b|c|rc)
203 [-_\.]?
204 [0-9]*
205 )?
206 (?: # post release
207 (?:-[0-9]+)|(?:[-_\.]?(post|rev|r)[-_\.]?[0-9]*)
208 )?
209 (?:[-_\.]?dev[-_\.]?[0-9]*)? # dev release
210 )
211 )
212 """
214 _regex = re.compile(
215 r"^\s*" + _operator_regex_str + _version_regex_str + r"\s*$",
216 re.VERBOSE | re.IGNORECASE,
217 )
219 _operators = {
220 "~=": "compatible",
221 "==": "equal",
222 "!=": "not_equal",
223 "<=": "less_than_equal",
224 ">=": "greater_than_equal",
225 "<": "less_than",
226 ">": "greater_than",
227 "===": "arbitrary",
228 }
230 def __init__(self, spec: str = "", prereleases: Optional[bool] = None) -> None:
231 """Initialize a Specifier instance.
233 :param spec:
234 The string representation of a specifier which will be parsed and
235 normalized before use.
236 :param prereleases:
237 This tells the specifier if it should accept prerelease versions if
238 applicable or not. The default of ``None`` will autodetect it from the
239 given specifiers.
240 :raises InvalidSpecifier:
241 If the given specifier is invalid (i.e. bad syntax).
242 """
243 match = self._regex.search(spec)
244 if not match:
245 raise InvalidSpecifier(f"Invalid specifier: '{spec}'")
247 self._spec: Tuple[str, str] = (
248 match.group("operator").strip(),
249 match.group("version").strip(),
250 )
252 # Store whether or not this Specifier should accept prereleases
253 self._prereleases = prereleases
255 @property
256 def prereleases(self) -> bool:
257 # If there is an explicit prereleases set for this, then we'll just
258 # blindly use that.
259 if self._prereleases is not None:
260 return self._prereleases
262 # Look at all of our specifiers and determine if they are inclusive
263 # operators, and if they are if they are including an explicit
264 # prerelease.
265 operator, version = self._spec
266 if operator in ["==", ">=", "<=", "~=", "==="]:
267 # The == specifier can include a trailing .*, if it does we
268 # want to remove before parsing.
269 if operator == "==" and version.endswith(".*"):
270 version = version[:-2]
272 # Parse the version, and if it is a pre-release than this
273 # specifier allows pre-releases.
274 if Version(version).is_prerelease:
275 return True
277 return False
279 @prereleases.setter
280 def prereleases(self, value: bool) -> None:
281 self._prereleases = value
283 @property
284 def operator(self) -> str:
285 """The operator of this specifier.
287 >>> Specifier("==1.2.3").operator
288 '=='
289 """
290 return self._spec[0]
292 @property
293 def version(self) -> str:
294 """The version of this specifier.
296 >>> Specifier("==1.2.3").version
297 '1.2.3'
298 """
299 return self._spec[1]
301 def __repr__(self) -> str:
302 """A representation of the Specifier that shows all internal state.
304 >>> Specifier('>=1.0.0')
305 <Specifier('>=1.0.0')>
306 >>> Specifier('>=1.0.0', prereleases=False)
307 <Specifier('>=1.0.0', prereleases=False)>
308 >>> Specifier('>=1.0.0', prereleases=True)
309 <Specifier('>=1.0.0', prereleases=True)>
310 """
311 pre = (
312 f", prereleases={self.prereleases!r}"
313 if self._prereleases is not None
314 else ""
315 )
317 return f"<{self.__class__.__name__}({str(self)!r}{pre})>"
319 def __str__(self) -> str:
320 """A string representation of the Specifier that can be round-tripped.
322 >>> str(Specifier('>=1.0.0'))
323 '>=1.0.0'
324 >>> str(Specifier('>=1.0.0', prereleases=False))
325 '>=1.0.0'
326 """
327 return "{}{}".format(*self._spec)
329 @property
330 def _canonical_spec(self) -> Tuple[str, str]:
331 canonical_version = canonicalize_version(
332 self._spec[1],
333 strip_trailing_zero=(self._spec[0] != "~="),
334 )
335 return self._spec[0], canonical_version
337 def __hash__(self) -> int:
338 return hash(self._canonical_spec)
340 def __eq__(self, other: object) -> bool:
341 """Whether or not the two Specifier-like objects are equal.
343 :param other: The other object to check against.
345 The value of :attr:`prereleases` is ignored.
347 >>> Specifier("==1.2.3") == Specifier("== 1.2.3.0")
348 True
349 >>> (Specifier("==1.2.3", prereleases=False) ==
350 ... Specifier("==1.2.3", prereleases=True))
351 True
352 >>> Specifier("==1.2.3") == "==1.2.3"
353 True
354 >>> Specifier("==1.2.3") == Specifier("==1.2.4")
355 False
356 >>> Specifier("==1.2.3") == Specifier("~=1.2.3")
357 False
358 """
359 if isinstance(other, str):
360 try:
361 other = self.__class__(str(other))
362 except InvalidSpecifier:
363 return NotImplemented
364 elif not isinstance(other, self.__class__):
365 return NotImplemented
367 return self._canonical_spec == other._canonical_spec
369 def _get_operator(self, op: str) -> CallableOperator:
370 operator_callable: CallableOperator = getattr(
371 self, f"_compare_{self._operators[op]}"
372 )
373 return operator_callable
375 def _compare_compatible(self, prospective: Version, spec: str) -> bool:
377 # Compatible releases have an equivalent combination of >= and ==. That
378 # is that ~=2.2 is equivalent to >=2.2,==2.*. This allows us to
379 # implement this in terms of the other specifiers instead of
380 # implementing it ourselves. The only thing we need to do is construct
381 # the other specifiers.
383 # We want everything but the last item in the version, but we want to
384 # ignore suffix segments.
385 prefix = ".".join(
386 list(itertools.takewhile(_is_not_suffix, _version_split(spec)))[:-1]
387 )
389 # Add the prefix notation to the end of our string
390 prefix += ".*"
392 return self._get_operator(">=")(prospective, spec) and self._get_operator("==")(
393 prospective, prefix
394 )
396 def _compare_equal(self, prospective: Version, spec: str) -> bool:
398 # We need special logic to handle prefix matching
399 if spec.endswith(".*"):
400 # In the case of prefix matching we want to ignore local segment.
401 normalized_prospective = canonicalize_version(prospective.public)
402 # Get the normalized version string ignoring the trailing .*
403 normalized_spec = canonicalize_version(spec[:-2], strip_trailing_zero=False)
404 # Split the spec out by dots, and pretend that there is an implicit
405 # dot in between a release segment and a pre-release segment.
406 split_spec = _version_split(normalized_spec)
408 # Split the prospective version out by dots, and pretend that there
409 # is an implicit dot in between a release segment and a pre-release
410 # segment.
411 split_prospective = _version_split(normalized_prospective)
413 # 0-pad the prospective version before shortening it to get the correct
414 # shortened version.
415 padded_prospective, _ = _pad_version(split_prospective, split_spec)
417 # Shorten the prospective version to be the same length as the spec
418 # so that we can determine if the specifier is a prefix of the
419 # prospective version or not.
420 shortened_prospective = padded_prospective[: len(split_spec)]
422 return shortened_prospective == split_spec
423 else:
424 # Convert our spec string into a Version
425 spec_version = Version(spec)
427 # If the specifier does not have a local segment, then we want to
428 # act as if the prospective version also does not have a local
429 # segment.
430 if not spec_version.local:
431 prospective = Version(prospective.public)
433 return prospective == spec_version
435 def _compare_not_equal(self, prospective: Version, spec: str) -> bool:
436 return not self._compare_equal(prospective, spec)
438 def _compare_less_than_equal(self, prospective: Version, spec: str) -> bool:
440 # NB: Local version identifiers are NOT permitted in the version
441 # specifier, so local version labels can be universally removed from
442 # the prospective version.
443 return Version(prospective.public) <= Version(spec)
445 def _compare_greater_than_equal(self, prospective: Version, spec: str) -> bool:
447 # NB: Local version identifiers are NOT permitted in the version
448 # specifier, so local version labels can be universally removed from
449 # the prospective version.
450 return Version(prospective.public) >= Version(spec)
452 def _compare_less_than(self, prospective: Version, spec_str: str) -> bool:
454 # Convert our spec to a Version instance, since we'll want to work with
455 # it as a version.
456 spec = Version(spec_str)
458 # Check to see if the prospective version is less than the spec
459 # version. If it's not we can short circuit and just return False now
460 # instead of doing extra unneeded work.
461 if not prospective < spec:
462 return False
464 # This special case is here so that, unless the specifier itself
465 # includes is a pre-release version, that we do not accept pre-release
466 # versions for the version mentioned in the specifier (e.g. <3.1 should
467 # not match 3.1.dev0, but should match 3.0.dev0).
468 if not spec.is_prerelease and prospective.is_prerelease:
469 if Version(prospective.base_version) == Version(spec.base_version):
470 return False
472 # If we've gotten to here, it means that prospective version is both
473 # less than the spec version *and* it's not a pre-release of the same
474 # version in the spec.
475 return True
477 def _compare_greater_than(self, prospective: Version, spec_str: str) -> bool:
479 # Convert our spec to a Version instance, since we'll want to work with
480 # it as a version.
481 spec = Version(spec_str)
483 # Check to see if the prospective version is greater than the spec
484 # version. If it's not we can short circuit and just return False now
485 # instead of doing extra unneeded work.
486 if not prospective > spec:
487 return False
489 # This special case is here so that, unless the specifier itself
490 # includes is a post-release version, that we do not accept
491 # post-release versions for the version mentioned in the specifier
492 # (e.g. >3.1 should not match 3.0.post0, but should match 3.2.post0).
493 if not spec.is_postrelease and prospective.is_postrelease:
494 if Version(prospective.base_version) == Version(spec.base_version):
495 return False
497 # Ensure that we do not allow a local version of the version mentioned
498 # in the specifier, which is technically greater than, to match.
499 if prospective.local is not None:
500 if Version(prospective.base_version) == Version(spec.base_version):
501 return False
503 # If we've gotten to here, it means that prospective version is both
504 # greater than the spec version *and* it's not a pre-release of the
505 # same version in the spec.
506 return True
508 def _compare_arbitrary(self, prospective: Version, spec: str) -> bool:
509 return str(prospective).lower() == str(spec).lower()
511 def __contains__(self, item: Union[str, Version]) -> bool:
512 """Return whether or not the item is contained in this specifier.
514 :param item: The item to check for.
516 This is used for the ``in`` operator and behaves the same as
517 :meth:`contains` with no ``prereleases`` argument passed.
519 >>> "1.2.3" in Specifier(">=1.2.3")
520 True
521 >>> Version("1.2.3") in Specifier(">=1.2.3")
522 True
523 >>> "1.0.0" in Specifier(">=1.2.3")
524 False
525 >>> "1.3.0a1" in Specifier(">=1.2.3")
526 False
527 >>> "1.3.0a1" in Specifier(">=1.2.3", prereleases=True)
528 True
529 """
530 return self.contains(item)
532 def contains(
533 self, item: UnparsedVersion, prereleases: Optional[bool] = None
534 ) -> bool:
535 """Return whether or not the item is contained in this specifier.
537 :param item:
538 The item to check for, which can be a version string or a
539 :class:`Version` instance.
540 :param prereleases:
541 Whether or not to match prereleases with this Specifier. If set to
542 ``None`` (the default), it uses :attr:`prereleases` to determine
543 whether or not prereleases are allowed.
545 >>> Specifier(">=1.2.3").contains("1.2.3")
546 True
547 >>> Specifier(">=1.2.3").contains(Version("1.2.3"))
548 True
549 >>> Specifier(">=1.2.3").contains("1.0.0")
550 False
551 >>> Specifier(">=1.2.3").contains("1.3.0a1")
552 False
553 >>> Specifier(">=1.2.3", prereleases=True).contains("1.3.0a1")
554 True
555 >>> Specifier(">=1.2.3").contains("1.3.0a1", prereleases=True)
556 True
557 """
559 # Determine if prereleases are to be allowed or not.
560 if prereleases is None:
561 prereleases = self.prereleases
563 # Normalize item to a Version, this allows us to have a shortcut for
564 # "2.0" in Specifier(">=2")
565 normalized_item = _coerce_version(item)
567 # Determine if we should be supporting prereleases in this specifier
568 # or not, if we do not support prereleases than we can short circuit
569 # logic if this version is a prereleases.
570 if normalized_item.is_prerelease and not prereleases:
571 return False
573 # Actually do the comparison to determine if this item is contained
574 # within this Specifier or not.
575 operator_callable: CallableOperator = self._get_operator(self.operator)
576 return operator_callable(normalized_item, self.version)
578 def filter(
579 self, iterable: Iterable[UnparsedVersionVar], prereleases: Optional[bool] = None
580 ) -> Iterator[UnparsedVersionVar]:
581 """Filter items in the given iterable, that match the specifier.
583 :param iterable:
584 An iterable that can contain version strings and :class:`Version` instances.
585 The items in the iterable will be filtered according to the specifier.
586 :param prereleases:
587 Whether or not to allow prereleases in the returned iterator. If set to
588 ``None`` (the default), it will be intelligently decide whether to allow
589 prereleases or not (based on the :attr:`prereleases` attribute, and
590 whether the only versions matching are prereleases).
592 This method is smarter than just ``filter(Specifier().contains, [...])``
593 because it implements the rule from :pep:`440` that a prerelease item
594 SHOULD be accepted if no other versions match the given specifier.
596 >>> list(Specifier(">=1.2.3").filter(["1.2", "1.3", "1.5a1"]))
597 ['1.3']
598 >>> list(Specifier(">=1.2.3").filter(["1.2", "1.2.3", "1.3", Version("1.4")]))
599 ['1.2.3', '1.3', <Version('1.4')>]
600 >>> list(Specifier(">=1.2.3").filter(["1.2", "1.5a1"]))
601 ['1.5a1']
602 >>> list(Specifier(">=1.2.3").filter(["1.3", "1.5a1"], prereleases=True))
603 ['1.3', '1.5a1']
604 >>> list(Specifier(">=1.2.3", prereleases=True).filter(["1.3", "1.5a1"]))
605 ['1.3', '1.5a1']
606 """
608 yielded = False
609 found_prereleases = []
611 kw = {"prereleases": prereleases if prereleases is not None else True}
613 # Attempt to iterate over all the values in the iterable and if any of
614 # them match, yield them.
615 for version in iterable:
616 parsed_version = _coerce_version(version)
618 if self.contains(parsed_version, **kw):
619 # If our version is a prerelease, and we were not set to allow
620 # prereleases, then we'll store it for later in case nothing
621 # else matches this specifier.
622 if parsed_version.is_prerelease and not (
623 prereleases or self.prereleases
624 ):
625 found_prereleases.append(version)
626 # Either this is not a prerelease, or we should have been
627 # accepting prereleases from the beginning.
628 else:
629 yielded = True
630 yield version
632 # Now that we've iterated over everything, determine if we've yielded
633 # any values, and if we have not and we have any prereleases stored up
634 # then we will go ahead and yield the prereleases.
635 if not yielded and found_prereleases:
636 for version in found_prereleases:
637 yield version
640_prefix_regex = re.compile(r"^([0-9]+)((?:a|b|c|rc)[0-9]+)$")
643def _version_split(version: str) -> List[str]:
644 result: List[str] = []
645 for item in version.split("."):
646 match = _prefix_regex.search(item)
647 if match:
648 result.extend(match.groups())
649 else:
650 result.append(item)
651 return result
654def _is_not_suffix(segment: str) -> bool:
655 return not any(
656 segment.startswith(prefix) for prefix in ("dev", "a", "b", "rc", "post")
657 )
660def _pad_version(left: List[str], right: List[str]) -> Tuple[List[str], List[str]]:
661 left_split, right_split = [], []
663 # Get the release segment of our versions
664 left_split.append(list(itertools.takewhile(lambda x: x.isdigit(), left)))
665 right_split.append(list(itertools.takewhile(lambda x: x.isdigit(), right)))
667 # Get the rest of our versions
668 left_split.append(left[len(left_split[0]) :])
669 right_split.append(right[len(right_split[0]) :])
671 # Insert our padding
672 left_split.insert(1, ["0"] * max(0, len(right_split[0]) - len(left_split[0])))
673 right_split.insert(1, ["0"] * max(0, len(left_split[0]) - len(right_split[0])))
675 return (list(itertools.chain(*left_split)), list(itertools.chain(*right_split)))
678class SpecifierSet(BaseSpecifier):
679 """This class abstracts handling of a set of version specifiers.
681 It can be passed a single specifier (``>=3.0``), a comma-separated list of
682 specifiers (``>=3.0,!=3.1``), or no specifier at all.
683 """
685 def __init__(
686 self, specifiers: str = "", prereleases: Optional[bool] = None
687 ) -> None:
688 """Initialize a SpecifierSet instance.
690 :param specifiers:
691 The string representation of a specifier or a comma-separated list of
692 specifiers which will be parsed and normalized before use.
693 :param prereleases:
694 This tells the SpecifierSet if it should accept prerelease versions if
695 applicable or not. The default of ``None`` will autodetect it from the
696 given specifiers.
698 :raises InvalidSpecifier:
699 If the given ``specifiers`` are not parseable than this exception will be
700 raised.
701 """
703 # Split on `,` to break each individual specifier into it's own item, and
704 # strip each item to remove leading/trailing whitespace.
705 split_specifiers = [s.strip() for s in specifiers.split(",") if s.strip()]
707 # Parsed each individual specifier, attempting first to make it a
708 # Specifier.
709 parsed: Set[Specifier] = set()
710 for specifier in split_specifiers:
711 parsed.add(Specifier(specifier))
713 # Turn our parsed specifiers into a frozen set and save them for later.
714 self._specs = frozenset(parsed)
716 # Store our prereleases value so we can use it later to determine if
717 # we accept prereleases or not.
718 self._prereleases = prereleases
720 @property
721 def prereleases(self) -> Optional[bool]:
722 # If we have been given an explicit prerelease modifier, then we'll
723 # pass that through here.
724 if self._prereleases is not None:
725 return self._prereleases
727 # If we don't have any specifiers, and we don't have a forced value,
728 # then we'll just return None since we don't know if this should have
729 # pre-releases or not.
730 if not self._specs:
731 return None
733 # Otherwise we'll see if any of the given specifiers accept
734 # prereleases, if any of them do we'll return True, otherwise False.
735 return any(s.prereleases for s in self._specs)
737 @prereleases.setter
738 def prereleases(self, value: bool) -> None:
739 self._prereleases = value
741 def __repr__(self) -> str:
742 """A representation of the specifier set that shows all internal state.
744 Note that the ordering of the individual specifiers within the set may not
745 match the input string.
747 >>> SpecifierSet('>=1.0.0,!=2.0.0')
748 <SpecifierSet('!=2.0.0,>=1.0.0')>
749 >>> SpecifierSet('>=1.0.0,!=2.0.0', prereleases=False)
750 <SpecifierSet('!=2.0.0,>=1.0.0', prereleases=False)>
751 >>> SpecifierSet('>=1.0.0,!=2.0.0', prereleases=True)
752 <SpecifierSet('!=2.0.0,>=1.0.0', prereleases=True)>
753 """
754 pre = (
755 f", prereleases={self.prereleases!r}"
756 if self._prereleases is not None
757 else ""
758 )
760 return f"<SpecifierSet({str(self)!r}{pre})>"
762 def __str__(self) -> str:
763 """A string representation of the specifier set that can be round-tripped.
765 Note that the ordering of the individual specifiers within the set may not
766 match the input string.
768 >>> str(SpecifierSet(">=1.0.0,!=1.0.1"))
769 '!=1.0.1,>=1.0.0'
770 >>> str(SpecifierSet(">=1.0.0,!=1.0.1", prereleases=False))
771 '!=1.0.1,>=1.0.0'
772 """
773 return ",".join(sorted(str(s) for s in self._specs))
775 def __hash__(self) -> int:
776 return hash(self._specs)
778 def __and__(self, other: Union["SpecifierSet", str]) -> "SpecifierSet":
779 """Return a SpecifierSet which is a combination of the two sets.
781 :param other: The other object to combine with.
783 >>> SpecifierSet(">=1.0.0,!=1.0.1") & '<=2.0.0,!=2.0.1'
784 <SpecifierSet('!=1.0.1,!=2.0.1,<=2.0.0,>=1.0.0')>
785 >>> SpecifierSet(">=1.0.0,!=1.0.1") & SpecifierSet('<=2.0.0,!=2.0.1')
786 <SpecifierSet('!=1.0.1,!=2.0.1,<=2.0.0,>=1.0.0')>
787 """
788 if isinstance(other, str):
789 other = SpecifierSet(other)
790 elif not isinstance(other, SpecifierSet):
791 return NotImplemented
793 specifier = SpecifierSet()
794 specifier._specs = frozenset(self._specs | other._specs)
796 if self._prereleases is None and other._prereleases is not None:
797 specifier._prereleases = other._prereleases
798 elif self._prereleases is not None and other._prereleases is None:
799 specifier._prereleases = self._prereleases
800 elif self._prereleases == other._prereleases:
801 specifier._prereleases = self._prereleases
802 else:
803 raise ValueError(
804 "Cannot combine SpecifierSets with True and False prerelease "
805 "overrides."
806 )
808 return specifier
810 def __eq__(self, other: object) -> bool:
811 """Whether or not the two SpecifierSet-like objects are equal.
813 :param other: The other object to check against.
815 The value of :attr:`prereleases` is ignored.
817 >>> SpecifierSet(">=1.0.0,!=1.0.1") == SpecifierSet(">=1.0.0,!=1.0.1")
818 True
819 >>> (SpecifierSet(">=1.0.0,!=1.0.1", prereleases=False) ==
820 ... SpecifierSet(">=1.0.0,!=1.0.1", prereleases=True))
821 True
822 >>> SpecifierSet(">=1.0.0,!=1.0.1") == ">=1.0.0,!=1.0.1"
823 True
824 >>> SpecifierSet(">=1.0.0,!=1.0.1") == SpecifierSet(">=1.0.0")
825 False
826 >>> SpecifierSet(">=1.0.0,!=1.0.1") == SpecifierSet(">=1.0.0,!=1.0.2")
827 False
828 """
829 if isinstance(other, (str, Specifier)):
830 other = SpecifierSet(str(other))
831 elif not isinstance(other, SpecifierSet):
832 return NotImplemented
834 return self._specs == other._specs
836 def __len__(self) -> int:
837 """Returns the number of specifiers in this specifier set."""
838 return len(self._specs)
840 def __iter__(self) -> Iterator[Specifier]:
841 """
842 Returns an iterator over all the underlying :class:`Specifier` instances
843 in this specifier set.
845 >>> sorted(SpecifierSet(">=1.0.0,!=1.0.1"), key=str)
846 [<Specifier('!=1.0.1')>, <Specifier('>=1.0.0')>]
847 """
848 return iter(self._specs)
850 def __contains__(self, item: UnparsedVersion) -> bool:
851 """Return whether or not the item is contained in this specifier.
853 :param item: The item to check for.
855 This is used for the ``in`` operator and behaves the same as
856 :meth:`contains` with no ``prereleases`` argument passed.
858 >>> "1.2.3" in SpecifierSet(">=1.0.0,!=1.0.1")
859 True
860 >>> Version("1.2.3") in SpecifierSet(">=1.0.0,!=1.0.1")
861 True
862 >>> "1.0.1" in SpecifierSet(">=1.0.0,!=1.0.1")
863 False
864 >>> "1.3.0a1" in SpecifierSet(">=1.0.0,!=1.0.1")
865 False
866 >>> "1.3.0a1" in SpecifierSet(">=1.0.0,!=1.0.1", prereleases=True)
867 True
868 """
869 return self.contains(item)
871 def contains(
872 self,
873 item: UnparsedVersion,
874 prereleases: Optional[bool] = None,
875 installed: Optional[bool] = None,
876 ) -> bool:
877 """Return whether or not the item is contained in this SpecifierSet.
879 :param item:
880 The item to check for, which can be a version string or a
881 :class:`Version` instance.
882 :param prereleases:
883 Whether or not to match prereleases with this SpecifierSet. If set to
884 ``None`` (the default), it uses :attr:`prereleases` to determine
885 whether or not prereleases are allowed.
887 >>> SpecifierSet(">=1.0.0,!=1.0.1").contains("1.2.3")
888 True
889 >>> SpecifierSet(">=1.0.0,!=1.0.1").contains(Version("1.2.3"))
890 True
891 >>> SpecifierSet(">=1.0.0,!=1.0.1").contains("1.0.1")
892 False
893 >>> SpecifierSet(">=1.0.0,!=1.0.1").contains("1.3.0a1")
894 False
895 >>> SpecifierSet(">=1.0.0,!=1.0.1", prereleases=True).contains("1.3.0a1")
896 True
897 >>> SpecifierSet(">=1.0.0,!=1.0.1").contains("1.3.0a1", prereleases=True)
898 True
899 """
900 # Ensure that our item is a Version instance.
901 if not isinstance(item, Version):
902 item = Version(item)
904 # Determine if we're forcing a prerelease or not, if we're not forcing
905 # one for this particular filter call, then we'll use whatever the
906 # SpecifierSet thinks for whether or not we should support prereleases.
907 if prereleases is None:
908 prereleases = self.prereleases
910 # We can determine if we're going to allow pre-releases by looking to
911 # see if any of the underlying items supports them. If none of them do
912 # and this item is a pre-release then we do not allow it and we can
913 # short circuit that here.
914 # Note: This means that 1.0.dev1 would not be contained in something
915 # like >=1.0.devabc however it would be in >=1.0.debabc,>0.0.dev0
916 if not prereleases and item.is_prerelease:
917 return False
919 if installed and item.is_prerelease:
920 item = Version(item.base_version)
922 # We simply dispatch to the underlying specs here to make sure that the
923 # given version is contained within all of them.
924 # Note: This use of all() here means that an empty set of specifiers
925 # will always return True, this is an explicit design decision.
926 return all(s.contains(item, prereleases=prereleases) for s in self._specs)
928 def filter(
929 self, iterable: Iterable[UnparsedVersionVar], prereleases: Optional[bool] = None
930 ) -> Iterator[UnparsedVersionVar]:
931 """Filter items in the given iterable, that match the specifiers in this set.
933 :param iterable:
934 An iterable that can contain version strings and :class:`Version` instances.
935 The items in the iterable will be filtered according to the specifier.
936 :param prereleases:
937 Whether or not to allow prereleases in the returned iterator. If set to
938 ``None`` (the default), it will be intelligently decide whether to allow
939 prereleases or not (based on the :attr:`prereleases` attribute, and
940 whether the only versions matching are prereleases).
942 This method is smarter than just ``filter(SpecifierSet(...).contains, [...])``
943 because it implements the rule from :pep:`440` that a prerelease item
944 SHOULD be accepted if no other versions match the given specifier.
946 >>> list(SpecifierSet(">=1.2.3").filter(["1.2", "1.3", "1.5a1"]))
947 ['1.3']
948 >>> list(SpecifierSet(">=1.2.3").filter(["1.2", "1.3", Version("1.4")]))
949 ['1.3', <Version('1.4')>]
950 >>> list(SpecifierSet(">=1.2.3").filter(["1.2", "1.5a1"]))
951 []
952 >>> list(SpecifierSet(">=1.2.3").filter(["1.3", "1.5a1"], prereleases=True))
953 ['1.3', '1.5a1']
954 >>> list(SpecifierSet(">=1.2.3", prereleases=True).filter(["1.3", "1.5a1"]))
955 ['1.3', '1.5a1']
957 An "empty" SpecifierSet will filter items based on the presence of prerelease
958 versions in the set.
960 >>> list(SpecifierSet("").filter(["1.3", "1.5a1"]))
961 ['1.3']
962 >>> list(SpecifierSet("").filter(["1.5a1"]))
963 ['1.5a1']
964 >>> list(SpecifierSet("", prereleases=True).filter(["1.3", "1.5a1"]))
965 ['1.3', '1.5a1']
966 >>> list(SpecifierSet("").filter(["1.3", "1.5a1"], prereleases=True))
967 ['1.3', '1.5a1']
968 """
969 # Determine if we're forcing a prerelease or not, if we're not forcing
970 # one for this particular filter call, then we'll use whatever the
971 # SpecifierSet thinks for whether or not we should support prereleases.
972 if prereleases is None:
973 prereleases = self.prereleases
975 # If we have any specifiers, then we want to wrap our iterable in the
976 # filter method for each one, this will act as a logical AND amongst
977 # each specifier.
978 if self._specs:
979 for spec in self._specs:
980 iterable = spec.filter(iterable, prereleases=bool(prereleases))
981 return iter(iterable)
982 # If we do not have any specifiers, then we need to have a rough filter
983 # which will filter out any pre-releases, unless there are no final
984 # releases.
985 else:
986 filtered: List[UnparsedVersionVar] = []
987 found_prereleases: List[UnparsedVersionVar] = []
989 for item in iterable:
990 parsed_version = _coerce_version(item)
992 # Store any item which is a pre-release for later unless we've
993 # already found a final version or we are accepting prereleases
994 if parsed_version.is_prerelease and not prereleases:
995 if not filtered:
996 found_prereleases.append(item)
997 else:
998 filtered.append(item)
1000 # If we've found no items except for pre-releases, then we'll go
1001 # ahead and use the pre-releases
1002 if not filtered and found_prereleases and prereleases is None:
1003 return iter(found_prereleases)
1005 return iter(filtered)