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
from __future__ import absolute_import, division, print_function
11
from ._compat import string_types, with_metaclass
12
from .version import Version, LegacyVersion, parse
15
class InvalidSpecifier(ValueError):
17
An invalid specifier was found, users should refer to PEP 440.
21
class BaseSpecifier(with_metaclass(abc.ABCMeta, object)):
26
Returns the str representation of this Specifier like object. This
27
should be representative of the Specifier itself.
33
Returns a hash value for this Specifier like object.
37
def __eq__(self, other):
39
Returns a boolean representing whether or not the two Specifier like
44
def __ne__(self, other):
46
Returns a boolean representing whether or not the two Specifier like
47
objects are not equal.
51
def prereleases(self):
53
Returns whether or not pre-releases as a whole are allowed by this
58
def prereleases(self, value):
60
Sets whether or not pre-releases as a whole are allowed by this
65
def contains(self, item, prereleases=None):
67
Determines if the given item is contained within this specifier.
71
def filter(self, iterable, prereleases=None):
73
Takes an iterable of items and filters them so that only items which
74
are contained within this specifier are allowed in it.
78
class _IndividualSpecifier(BaseSpecifier):
82
def __init__(self, spec="", prereleases=None):
83
match = self._regex.search(spec)
85
raise InvalidSpecifier("Invalid specifier: '{0}'".format(spec))
88
match.group("operator").strip(),
89
match.group("version").strip(),
92
# Store whether or not this Specifier should accept prereleases
93
self._prereleases = prereleases
97
", prereleases={0!r}".format(self.prereleases)
98
if self._prereleases is not None
102
return "<{0}({1!r}{2})>".format(
103
self.__class__.__name__,
109
return "{0}{1}".format(*self._spec)
112
return hash(self._spec)
114
def __eq__(self, other):
115
if isinstance(other, string_types):
117
other = self.__class__(other)
118
except InvalidSpecifier:
119
return NotImplemented
120
elif not isinstance(other, self.__class__):
121
return NotImplemented
123
return self._spec == other._spec
125
def __ne__(self, other):
126
if isinstance(other, string_types):
128
other = self.__class__(other)
129
except InvalidSpecifier:
130
return NotImplemented
131
elif not isinstance(other, self.__class__):
132
return NotImplemented
134
return self._spec != other._spec
136
def _get_operator(self, op):
137
return getattr(self, "_compare_{0}".format(self._operators[op]))
139
def _coerce_version(self, version):
140
if not isinstance(version, (LegacyVersion, Version)):
141
version = parse(version)
153
def prereleases(self):
154
return self._prereleases
157
def prereleases(self, value):
158
self._prereleases = value
160
def __contains__(self, item):
161
return self.contains(item)
163
def contains(self, item, prereleases=None):
164
# Determine if prereleases are to be allowed or not.
165
if prereleases is None:
166
prereleases = self.prereleases
168
# Normalize item to a Version or LegacyVersion, this allows us to have
169
# a shortcut for ``"2.0" in Specifier(">=2")
170
item = self._coerce_version(item)
172
# Determine if we should be supporting prereleases in this specifier
173
# or not, if we do not support prereleases than we can short circuit
174
# logic if this version is a prereleases.
175
if item.is_prerelease and not prereleases:
178
# Actually do the comparison to determine if this item is contained
179
# within this Specifier or not.
180
return self._get_operator(self.operator)(item, self.version)
182
def filter(self, iterable, prereleases=None):
184
found_prereleases = []
186
kw = {"prereleases": prereleases if prereleases is not None else True}
188
# Attempt to iterate over all the values in the iterable and if any of
189
# them match, yield them.
190
for version in iterable:
191
parsed_version = self._coerce_version(version)
193
if self.contains(parsed_version, **kw):
194
# If our version is a prerelease, and we were not set to allow
195
# prereleases, then we'll store it for later incase nothing
196
# else matches this specifier.
197
if (parsed_version.is_prerelease and not
198
(prereleases or self.prereleases)):
199
found_prereleases.append(version)
200
# Either this is not a prerelease, or we should have been
201
# accepting prereleases from the begining.
206
# Now that we've iterated over everything, determine if we've yielded
207
# any values, and if we have not and we have any prereleases stored up
208
# then we will go ahead and yield the prereleases.
209
if not yielded and found_prereleases:
210
for version in found_prereleases:
214
class LegacySpecifier(_IndividualSpecifier):
218
(?P<operator>(==|!=|<=|>=|<|>))
221
[^,;\s)]* # Since this is a "legacy" specifier, and the version
222
# string can be just about anything, we match everything
223
# except for whitespace, a semi-colon for marker support,
224
# a closing paren since versions can be enclosed in
225
# them, and a comma since it's a version separator.
231
r"^\s*" + _regex_str + r"\s*$", re.VERBOSE | re.IGNORECASE)
236
"<=": "less_than_equal",
237
">=": "greater_than_equal",
242
def _coerce_version(self, version):
243
if not isinstance(version, LegacyVersion):
244
version = LegacyVersion(str(version))
247
def _compare_equal(self, prospective, spec):
248
return prospective == self._coerce_version(spec)
250
def _compare_not_equal(self, prospective, spec):
251
return prospective != self._coerce_version(spec)
253
def _compare_less_than_equal(self, prospective, spec):
254
return prospective <= self._coerce_version(spec)
256
def _compare_greater_than_equal(self, prospective, spec):
257
return prospective >= self._coerce_version(spec)
259
def _compare_less_than(self, prospective, spec):
260
return prospective < self._coerce_version(spec)
262
def _compare_greater_than(self, prospective, spec):
263
return prospective > self._coerce_version(spec)
266
def _require_version_compare(fn):
268
def wrapped(self, prospective, spec):
269
if not isinstance(prospective, Version):
271
return fn(self, prospective, spec)
275
class Specifier(_IndividualSpecifier):
279
(?P<operator>(~=|==|!=|<=|>=|<|>|===))
282
# The identity operators allow for an escape hatch that will
283
# do an exact string match of the version you wish to install.
284
# This will not be parsed by PEP 440 and we cannot determine
285
# any semantic meaning from it. This operator is discouraged
286
# but included entirely as an escape hatch.
287
(?<====) # Only match for the identity operator
289
[^\s]* # We just match everything, except for whitespace
290
# since we are only testing for strict identity.
294
# The (non)equality operators allow for wild card and local
295
# versions to be specified so we have to define these two
296
# operators separately to enable that.
297
(?<===|!=) # Only match for equals and not equals
302
[0-9]+(?:\.[0-9]+)* # release
305
(a|b|c|rc|alpha|beta|pre|preview)
310
(?:-[0-9]+)|(?:[-_\.]?(post|rev|r)[-_\.]?[0-9]*)
313
# You cannot use a wild card and a dev or local version
314
# together so group them with a | and make them optional.
316
(?:[-_\.]?dev[-_\.]?[0-9]*)? # dev release
317
(?:\+[a-z0-9]+(?:[-_\.][a-z0-9]+)*)? # local
319
\.\* # Wild card syntax of .*
324
# The compatible operator requires at least two digits in the
326
(?<=~=) # Only match for the compatible operator
331
[0-9]+(?:\.[0-9]+)+ # release (We have a + instead of a *)
334
(a|b|c|rc|alpha|beta|pre|preview)
339
(?:-[0-9]+)|(?:[-_\.]?(post|rev|r)[-_\.]?[0-9]*)
341
(?:[-_\.]?dev[-_\.]?[0-9]*)? # dev release
345
# All other operators only allow a sub set of what the
346
# (non)equality operators do. Specifically they do not allow
347
# local versions to be specified nor do they allow the prefix
348
# matching wild cards.
349
(?<!==|!=|~=) # We have special cases for these
350
# operators so we want to make sure they
356
[0-9]+(?:\.[0-9]+)* # release
359
(a|b|c|rc|alpha|beta|pre|preview)
364
(?:-[0-9]+)|(?:[-_\.]?(post|rev|r)[-_\.]?[0-9]*)
366
(?:[-_\.]?dev[-_\.]?[0-9]*)? # dev release
373
r"^\s*" + _regex_str + r"\s*$", re.VERBOSE | re.IGNORECASE)
379
"<=": "less_than_equal",
380
">=": "greater_than_equal",
386
@_require_version_compare
387
def _compare_compatible(self, prospective, spec):
388
# Compatible releases have an equivalent combination of >= and ==. That
389
# is that ~=2.2 is equivalent to >=2.2,==2.*. This allows us to
390
# implement this in terms of the other specifiers instead of
391
# implementing it ourselves. The only thing we need to do is construct
392
# the other specifiers.
394
# We want everything but the last item in the version, but we want to
395
# ignore post and dev releases and we want to treat the pre-release as
396
# it's own separate segment.
400
lambda x: (not x.startswith("post") and not
401
x.startswith("dev")),
402
_version_split(spec),
407
# Add the prefix notation to the end of our string
410
return (self._get_operator(">=")(prospective, spec) and
411
self._get_operator("==")(prospective, prefix))
413
@_require_version_compare
414
def _compare_equal(self, prospective, spec):
415
# We need special logic to handle prefix matching
416
if spec.endswith(".*"):
417
# In the case of prefix matching we want to ignore local segment.
418
prospective = Version(prospective.public)
419
# Split the spec out by dots, and pretend that there is an implicit
420
# dot in between a release segment and a pre-release segment.
421
spec = _version_split(spec[:-2]) # Remove the trailing .*
423
# Split the prospective version out by dots, and pretend that there
424
# is an implicit dot in between a release segment and a pre-release
426
prospective = _version_split(str(prospective))
428
# Shorten the prospective version to be the same length as the spec
429
# so that we can determine if the specifier is a prefix of the
430
# prospective version or not.
431
prospective = prospective[:len(spec)]
433
# Pad out our two sides with zeros so that they both equal the same
435
spec, prospective = _pad_version(spec, prospective)
437
# Convert our spec string into a Version
440
# If the specifier does not have a local segment, then we want to
441
# act as if the prospective version also does not have a local
444
prospective = Version(prospective.public)
446
return prospective == spec
448
@_require_version_compare
449
def _compare_not_equal(self, prospective, spec):
450
return not self._compare_equal(prospective, spec)
452
@_require_version_compare
453
def _compare_less_than_equal(self, prospective, spec):
454
return prospective <= Version(spec)
456
@_require_version_compare
457
def _compare_greater_than_equal(self, prospective, spec):
458
return prospective >= Version(spec)
460
@_require_version_compare
461
def _compare_less_than(self, prospective, spec):
462
# Convert our spec to a Version instance, since we'll want to work with
466
# Check to see if the prospective version is less than the spec
467
# version. If it's not we can short circuit and just return False now
468
# instead of doing extra unneeded work.
469
if not prospective < spec:
472
# This special case is here so that, unless the specifier itself
473
# includes is a pre-release version, that we do not accept pre-release
474
# versions for the version mentioned in the specifier (e.g. <3.1 should
475
# not match 3.1.dev0, but should match 3.0.dev0).
476
if not spec.is_prerelease and prospective.is_prerelease:
477
if Version(prospective.base_version) == Version(spec.base_version):
480
# If we've gotten to here, it means that prospective version is both
481
# less than the spec version *and* it's not a pre-release of the same
482
# version in the spec.
485
@_require_version_compare
486
def _compare_greater_than(self, prospective, spec):
487
# Convert our spec to a Version instance, since we'll want to work with
491
# Check to see if the prospective version is greater than the spec
492
# version. If it's not we can short circuit and just return False now
493
# instead of doing extra unneeded work.
494
if not prospective > spec:
497
# This special case is here so that, unless the specifier itself
498
# includes is a post-release version, that we do not accept
499
# post-release versions for the version mentioned in the specifier
500
# (e.g. >3.1 should not match 3.0.post0, but should match 3.2.post0).
501
if not spec.is_postrelease and prospective.is_postrelease:
502
if Version(prospective.base_version) == Version(spec.base_version):
505
# Ensure that we do not allow a local version of the version mentioned
506
# in the specifier, which is techincally greater than, to match.
507
if prospective.local is not None:
508
if Version(prospective.base_version) == Version(spec.base_version):
511
# If we've gotten to here, it means that prospective version is both
512
# greater than the spec version *and* it's not a pre-release of the
513
# same version in the spec.
516
def _compare_arbitrary(self, prospective, spec):
517
return str(prospective).lower() == str(spec).lower()
520
def prereleases(self):
521
# If there is an explicit prereleases set for this, then we'll just
523
if self._prereleases is not None:
524
return self._prereleases
526
# Look at all of our specifiers and determine if they are inclusive
527
# operators, and if they are if they are including an explicit
529
operator, version = self._spec
530
if operator in ["==", ">=", "<=", "~=", "==="]:
531
# The == specifier can include a trailing .*, if it does we
532
# want to remove before parsing.
533
if operator == "==" and version.endswith(".*"):
534
version = version[:-2]
536
# Parse the version, and if it is a pre-release than this
537
# specifier allows pre-releases.
538
if parse(version).is_prerelease:
544
def prereleases(self, value):
545
self._prereleases = value
548
_prefix_regex = re.compile(r"^([0-9]+)((?:a|b|c|rc)[0-9]+)$")
551
def _version_split(version):
553
for item in version.split("."):
554
match = _prefix_regex.search(item)
556
result.extend(match.groups())
562
def _pad_version(left, right):
563
left_split, right_split = [], []
565
# Get the release segment of our versions
566
left_split.append(list(itertools.takewhile(lambda x: x.isdigit(), left)))
567
right_split.append(list(itertools.takewhile(lambda x: x.isdigit(), right)))
569
# Get the rest of our versions
570
left_split.append(left[len(left_split[0]):])
571
right_split.append(right[len(right_split[0]):])
576
["0"] * max(0, len(right_split[0]) - len(left_split[0])),
580
["0"] * max(0, len(left_split[0]) - len(right_split[0])),
584
list(itertools.chain(*left_split)),
585
list(itertools.chain(*right_split)),
589
class SpecifierSet(BaseSpecifier):
591
def __init__(self, specifiers="", prereleases=None):
592
# Split on , to break each indidivual specifier into it's own item, and
593
# strip each item to remove leading/trailing whitespace.
594
specifiers = [s.strip() for s in specifiers.split(",") if s.strip()]
596
# Parsed each individual specifier, attempting first to make it a
597
# Specifier and falling back to a LegacySpecifier.
599
for specifier in specifiers:
601
parsed.add(Specifier(specifier))
602
except InvalidSpecifier:
603
parsed.add(LegacySpecifier(specifier))
605
# Turn our parsed specifiers into a frozen set and save them for later.
606
self._specs = frozenset(parsed)
608
# Store our prereleases value so we can use it later to determine if
609
# we accept prereleases or not.
610
self._prereleases = prereleases
614
", prereleases={0!r}".format(self.prereleases)
615
if self._prereleases is not None
619
return "<SpecifierSet({0!r}{1})>".format(str(self), pre)
622
return ",".join(sorted(str(s) for s in self._specs))
625
return hash(self._specs)
627
def __and__(self, other):
628
if isinstance(other, string_types):
629
other = SpecifierSet(other)
630
elif not isinstance(other, SpecifierSet):
631
return NotImplemented
633
specifier = SpecifierSet()
634
specifier._specs = frozenset(self._specs | other._specs)
636
if self._prereleases is None and other._prereleases is not None:
637
specifier._prereleases = other._prereleases
638
elif self._prereleases is not None and other._prereleases is None:
639
specifier._prereleases = self._prereleases
640
elif self._prereleases == other._prereleases:
641
specifier._prereleases = self._prereleases
644
"Cannot combine SpecifierSets with True and False prerelease "
650
def __eq__(self, other):
651
if isinstance(other, string_types):
652
other = SpecifierSet(other)
653
elif isinstance(other, _IndividualSpecifier):
654
other = SpecifierSet(str(other))
655
elif not isinstance(other, SpecifierSet):
656
return NotImplemented
658
return self._specs == other._specs
660
def __ne__(self, other):
661
if isinstance(other, string_types):
662
other = SpecifierSet(other)
663
elif isinstance(other, _IndividualSpecifier):
664
other = SpecifierSet(str(other))
665
elif not isinstance(other, SpecifierSet):
666
return NotImplemented
668
return self._specs != other._specs
671
return len(self._specs)
674
return iter(self._specs)
677
def prereleases(self):
678
# If we have been given an explicit prerelease modifier, then we'll
679
# pass that through here.
680
if self._prereleases is not None:
681
return self._prereleases
683
# If we don't have any specifiers, and we don't have a forced value,
684
# then we'll just return None since we don't know if this should have
685
# pre-releases or not.
689
# Otherwise we'll see if any of the given specifiers accept
690
# prereleases, if any of them do we'll return True, otherwise False.
691
return any(s.prereleases for s in self._specs)
694
def prereleases(self, value):
695
self._prereleases = value
697
def __contains__(self, item):
698
return self.contains(item)
700
def contains(self, item, prereleases=None):
701
# Ensure that our item is a Version or LegacyVersion instance.
702
if not isinstance(item, (LegacyVersion, Version)):
705
# Determine if we're forcing a prerelease or not, if we're not forcing
706
# one for this particular filter call, then we'll use whatever the
707
# SpecifierSet thinks for whether or not we should support prereleases.
708
if prereleases is None:
709
prereleases = self.prereleases
711
# We can determine if we're going to allow pre-releases by looking to
712
# see if any of the underlying items supports them. If none of them do
713
# and this item is a pre-release then we do not allow it and we can
714
# short circuit that here.
715
# Note: This means that 1.0.dev1 would not be contained in something
716
# like >=1.0.devabc however it would be in >=1.0.debabc,>0.0.dev0
717
if not prereleases and item.is_prerelease:
720
# We simply dispatch to the underlying specs here to make sure that the
721
# given version is contained within all of them.
722
# Note: This use of all() here means that an empty set of specifiers
723
# will always return True, this is an explicit design decision.
725
s.contains(item, prereleases=prereleases)
729
def filter(self, iterable, prereleases=None):
730
# Determine if we're forcing a prerelease or not, if we're not forcing
731
# one for this particular filter call, then we'll use whatever the
732
# SpecifierSet thinks for whether or not we should support prereleases.
733
if prereleases is None:
734
prereleases = self.prereleases
736
# If we have any specifiers, then we want to wrap our iterable in the
737
# filter method for each one, this will act as a logical AND amongst
740
for spec in self._specs:
741
iterable = spec.filter(iterable, prereleases=bool(prereleases))
743
# If we do not have any specifiers, then we need to have a rough filter
744
# which will filter out any pre-releases, unless there are no final
745
# releases, and which will filter out LegacyVersion in general.
748
found_prereleases = []
750
for item in iterable:
751
# Ensure that we some kind of Version class for this item.
752
if not isinstance(item, (LegacyVersion, Version)):
753
parsed_version = parse(item)
755
parsed_version = item
757
# Filter out any item which is parsed as a LegacyVersion
758
if isinstance(parsed_version, LegacyVersion):
761
# Store any item which is a pre-release for later unless we've
762
# already found a final version or we are accepting prereleases
763
if parsed_version.is_prerelease and not prereleases:
765
found_prereleases.append(item)
767
filtered.append(item)
769
# If we've found no items except for pre-releases, then we'll go
770
# ahead and use the pre-releases
771
if not filtered and found_prereleases and prereleases is None:
772
return found_prereleases