Specifiers#
A core requirement of dealing with dependencies is the ability to specify what versions of a dependency are acceptable for you.
See Version Specifiers Specification for more details on the exact format implemented in this module, for use in Python Packaging tooling.
Usage#
>>> from packaging.specifiers import SpecifierSet
>>> from packaging.version import Version
>>> spec1 = SpecifierSet("~=1.0")
>>> spec1
<SpecifierSet('~=1.0')>
>>> spec2 = SpecifierSet(">=1.0")
>>> spec2
<SpecifierSet('>=1.0')>
>>> # We can combine specifiers
>>> combined_spec = spec1 & spec2
>>> combined_spec
<SpecifierSet('>=1.0,~=1.0')>
>>> # We can also implicitly combine a string specifier
>>> combined_spec &= "!=1.1"
>>> combined_spec
<SpecifierSet('!=1.1,>=1.0,~=1.0')>
>>> # We can iterate over the SpecifierSet to recover the
>>> # individual specifiers
>>> sorted(combined_spec, key=str)
[<Specifier('!=1.1')>, <Specifier('>=1.0')>, <Specifier('~=1.0')>]
>>> # Create a few versions to check for contains.
>>> v1 = Version("1.0a5")
>>> v2 = Version("1.0")
>>> # We can check a version object to see if it falls within a specifier
>>> v1 in combined_spec
False
>>> v2 in combined_spec
True
>>> # We can even do the same with a string based version
>>> "1.4" in combined_spec
True
>>> # Finally we can filter a list of versions to get only those which are
>>> # contained within our specifier.
>>> list(combined_spec.filter([v1, v2, "1.4"]))
[<Version('1.0')>, '1.4']
Reference#
- exception packaging.specifiers.InvalidSpecifier#
Raised when attempting to create a
Specifier
with a specifier string that is invalid.>>> Specifier("lolwat") Traceback (most recent call last): ... packaging.specifiers.InvalidSpecifier: Invalid specifier: 'lolwat'
- __weakref__#
list of weak references to the object (if defined)
- class packaging.specifiers.Specifier#
This class abstracts handling of version specifiers.
Tip
It is generally not required to instantiate this manually. You should instead prefer to work with
SpecifierSet
instead, which can parse comma-separated version specifiers (which is what package metadata contains).- __init__(spec='', prereleases=None)#
Initialize a Specifier instance.
- Parameters:
- Raises:
InvalidSpecifier – If the given specifier is invalid (i.e. bad syntax).
- Return type:
None
- property prereleases: bool#
Whether or not pre-releases as a whole are allowed.
This can be set to either
True
orFalse
to explicitly enable or disable prereleases or it can be set toNone
(the default) to use default semantics.
- __repr__()#
A representation of the Specifier that shows all internal state.
>>> Specifier('>=1.0.0') <Specifier('>=1.0.0')> >>> Specifier('>=1.0.0', prereleases=False) <Specifier('>=1.0.0', prereleases=False)> >>> Specifier('>=1.0.0', prereleases=True) <Specifier('>=1.0.0', prereleases=True)>
- Return type:
- __str__()#
A string representation of the Specifier that can be round-tripped.
>>> str(Specifier('>=1.0.0')) '>=1.0.0' >>> str(Specifier('>=1.0.0', prereleases=False)) '>=1.0.0'
- Return type:
- __eq__(other)#
Whether or not the two Specifier-like objects are equal.
The value of
prereleases
is ignored.>>> Specifier("==1.2.3") == Specifier("== 1.2.3.0") True >>> (Specifier("==1.2.3", prereleases=False) == ... Specifier("==1.2.3", prereleases=True)) True >>> Specifier("==1.2.3") == "==1.2.3" True >>> Specifier("==1.2.3") == Specifier("==1.2.4") False >>> Specifier("==1.2.3") == Specifier("~=1.2.3") False
- __contains__(item)#
Return whether or not the item is contained in this specifier.
This is used for the
in
operator and behaves the same ascontains()
with noprereleases
argument passed.>>> "1.2.3" in Specifier(">=1.2.3") True >>> Version("1.2.3") in Specifier(">=1.2.3") True >>> "1.0.0" in Specifier(">=1.2.3") False >>> "1.3.0a1" in Specifier(">=1.2.3") False >>> "1.3.0a1" in Specifier(">=1.2.3", prereleases=True) True
- contains(item, prereleases=None)#
Return whether or not the item is contained in this specifier.
- Parameters:
item (UnparsedVersion) – The item to check for, which can be a version string or a
Version
instance.prereleases (bool | None) – Whether or not to match prereleases with this Specifier. If set to
None
(the default), it usesprereleases
to determine whether or not prereleases are allowed.
- Return type:
>>> Specifier(">=1.2.3").contains("1.2.3") True >>> Specifier(">=1.2.3").contains(Version("1.2.3")) True >>> 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) True
- filter(iterable, prereleases=None)#
Filter items in the given iterable, that match the specifier.
- Parameters:
iterable (Iterable[UnparsedVersionVar]) – An iterable that can contain version strings and
Version
instances. The items in the iterable will be filtered according to the specifier.prereleases (bool | None) – 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 theprereleases
attribute, and whether the only versions matching are prereleases).
- Return type:
Iterator[UnparsedVersionVar]
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.>>> list(Specifier(">=1.2.3").filter(["1.2", "1.3", "1.5a1"])) ['1.3'] >>> list(Specifier(">=1.2.3").filter(["1.2", "1.2.3", "1.3", Version("1.4")])) ['1.2.3', '1.3', <Version('1.4')>] >>> list(Specifier(">=1.2.3").filter(["1.2", "1.5a1"])) ['1.5a1'] >>> list(Specifier(">=1.2.3").filter(["1.3", "1.5a1"], prereleases=True)) ['1.3', '1.5a1'] >>> list(Specifier(">=1.2.3", prereleases=True).filter(["1.3", "1.5a1"])) ['1.3', '1.5a1']
- class packaging.specifiers.SpecifierSet#
This class abstracts handling of a set of version specifiers.
It can be passed a single specifier (
>=3.0
), a comma-separated list of specifiers (>=3.0,!=3.1
), or no specifier at all.- __init__(specifiers='', prereleases=None)#
Initialize a SpecifierSet instance.
- Parameters:
specifiers (str) – The string representation of a specifier or a comma-separated list of specifiers which will be parsed and normalized before use.
prereleases (bool | None) – This tells the SpecifierSet if it should accept prerelease versions if applicable or not. The default of
None
will autodetect it from the given specifiers.
- Raises:
InvalidSpecifier – If the given
specifiers
are not parseable than this exception will be raised.- Return type:
None
- property prereleases: bool | None#
Whether or not pre-releases as a whole are allowed.
This can be set to either
True
orFalse
to explicitly enable or disable prereleases or it can be set toNone
(the default) to use default semantics.
- __repr__()#
A representation of the specifier set that shows all internal state.
Note that the ordering of the individual specifiers within the set may not match the input string.
>>> SpecifierSet('>=1.0.0,!=2.0.0') <SpecifierSet('!=2.0.0,>=1.0.0')> >>> SpecifierSet('>=1.0.0,!=2.0.0', prereleases=False) <SpecifierSet('!=2.0.0,>=1.0.0', prereleases=False)> >>> SpecifierSet('>=1.0.0,!=2.0.0', prereleases=True) <SpecifierSet('!=2.0.0,>=1.0.0', prereleases=True)>
- Return type:
- __str__()#
A string representation of the specifier set that can be round-tripped.
Note that the ordering of the individual specifiers within the set may not match the input string.
>>> str(SpecifierSet(">=1.0.0,!=1.0.1")) '!=1.0.1,>=1.0.0' >>> str(SpecifierSet(">=1.0.0,!=1.0.1", prereleases=False)) '!=1.0.1,>=1.0.0'
- Return type:
- __and__(other)#
Return a SpecifierSet which is a combination of the two sets.
- Parameters:
other (SpecifierSet | str) – The other object to combine with.
- Return type:
>>> SpecifierSet(">=1.0.0,!=1.0.1") & '<=2.0.0,!=2.0.1' <SpecifierSet('!=1.0.1,!=2.0.1,<=2.0.0,>=1.0.0')> >>> SpecifierSet(">=1.0.0,!=1.0.1") & SpecifierSet('<=2.0.0,!=2.0.1') <SpecifierSet('!=1.0.1,!=2.0.1,<=2.0.0,>=1.0.0')>
- __eq__(other)#
Whether or not the two SpecifierSet-like objects are equal.
The value of
prereleases
is ignored.>>> SpecifierSet(">=1.0.0,!=1.0.1") == SpecifierSet(">=1.0.0,!=1.0.1") True >>> (SpecifierSet(">=1.0.0,!=1.0.1", prereleases=False) == ... SpecifierSet(">=1.0.0,!=1.0.1", prereleases=True)) True >>> SpecifierSet(">=1.0.0,!=1.0.1") == ">=1.0.0,!=1.0.1" True >>> SpecifierSet(">=1.0.0,!=1.0.1") == SpecifierSet(">=1.0.0") False >>> SpecifierSet(">=1.0.0,!=1.0.1") == SpecifierSet(">=1.0.0,!=1.0.2") False
- __iter__()#
Returns an iterator over all the underlying
Specifier
instances in this specifier set.>>> sorted(SpecifierSet(">=1.0.0,!=1.0.1"), key=str) [<Specifier('!=1.0.1')>, <Specifier('>=1.0.0')>]
- __contains__(item)#
Return whether or not the item is contained in this specifier.
This is used for the
in
operator and behaves the same ascontains()
with noprereleases
argument passed.>>> "1.2.3" in SpecifierSet(">=1.0.0,!=1.0.1") True >>> Version("1.2.3") in SpecifierSet(">=1.0.0,!=1.0.1") True >>> "1.0.1" in SpecifierSet(">=1.0.0,!=1.0.1") False >>> "1.3.0a1" in SpecifierSet(">=1.0.0,!=1.0.1") False >>> "1.3.0a1" in SpecifierSet(">=1.0.0,!=1.0.1", prereleases=True) True
- contains(item, prereleases=None, installed=None)#
Return whether or not the item is contained in this SpecifierSet.
- Parameters:
item (UnparsedVersion) – The item to check for, which can be a version string or a
Version
instance.prereleases (bool | None) – Whether or not to match prereleases with this SpecifierSet. If set to
None
(the default), it usesprereleases
to determine whether or not prereleases are allowed.installed (bool | None) –
- Return type:
>>> SpecifierSet(">=1.0.0,!=1.0.1").contains("1.2.3") True >>> SpecifierSet(">=1.0.0,!=1.0.1").contains(Version("1.2.3")) True >>> 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").contains("1.3.0a1", prereleases=True) True
- filter(iterable, prereleases=None)#
Filter items in the given iterable, that match the specifiers in this set.
- Parameters:
iterable (Iterable[UnparsedVersionVar]) – An iterable that can contain version strings and
Version
instances. The items in the iterable will be filtered according to the specifier.prereleases (bool | None) – 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 theprereleases
attribute, and whether the only versions matching are prereleases).
- Return type:
Iterator[UnparsedVersionVar]
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.>>> 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"])) [] >>> 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"])) ['1.3', '1.5a1']
An “empty” SpecifierSet will filter items based on the presence of prerelease versions in the set.
>>> list(SpecifierSet("").filter(["1.3", "1.5a1"])) ['1.3'] >>> list(SpecifierSet("").filter(["1.5a1"])) ['1.5a1'] >>> list(SpecifierSet("", prereleases=True).filter(["1.3", "1.5a1"])) ['1.3', '1.5a1'] >>> list(SpecifierSet("").filter(["1.3", "1.5a1"], prereleases=True)) ['1.3', '1.5a1']